POST /subscriptions

Register one webhook endpoint, its secret and the filter it wants.

POST /subscriptions

Registers an endpoint to POST matching changes to. endpoint and secret are required; an id is minted when none is given, and name defaults to the endpoint.

The endpoint is checked here, not only at delivery. It must be an http(s) URL, and cleartext http is admitted only to loopback, where a subscriber is a sidecar with no hop to wiretap. A delivery carries both what changed — which is metadata about what an organisation is watching — and the signature that says the bytes are this service’s, so registering an endpoint every delivery to it would refuse is refused while somebody can still do something about it.

Authentication

No authentication requirement is stated for this operation.

Request body

A JSON object; anything else, or nothing at all, is refused. A member the operation does not read is ignored rather than refused, which is the opposite of what the serving API does with an unknown field and is stated here because a caller who misspells one is answered rather than corrected. The whole body is read into memory before it is parsed, so put a proxy in front of anything that is not trusted to be small.

application/json, required — SubscriptionRegistration

{
  "endpoint": "https://subscriber.example.invalid/hooks/openregs",
  "filter": {
    "entity_type": [
      "operator"
    ],
    "regime": [
      "fixreg"
    ]
  },
  "name": "downstream-ci",
  "secret": "the-shared-secret-this-subscriber-verifies-with"
}

Responses

201

The subscription as registered, without its secret.

application/json — SubscriptionCreated

400

the body is not a JSON object, states no endpoint or no secret, names a filter dimension that does not exist, gives an endpoint that is not an http(s) URL or is cleartext off loopback, or reuses an id that is already registered

application/json — Error