Register a webhook destination

post

https://api.qfp.quantnetwork.net/api/webhooks

Registers a destination for the organisation and returns it.

Signing and secrets

On HMAC_SHA256 the response carries the generated secret. The platform generates it; a caller cannot supply one, and no read returns it afterwards. An organisation that loses it must rotate. On JWS_ES256 no secret is generated, and deliveries are verified against the platform's published public key instead.

Destination requirements

The URL must use https://, and its host must resolve to a publicly routable address. Private ranges, loopback, link-local and carrier-grade NAT are refused, and redirects are not followed at delivery time. The stored URL is normalised, with scheme and host lowercased and a default :443 dropped, so a later read may return it in a different case.

Duplicate destinations

Registering a URL the organisation already holds returns 409 Conflict. Uniqueness is per organisation.

Default signing scheme

signatureScheme may be omitted, in which case HMAC_SHA256 is used. An unrecognised value is rejected rather than defaulted.

Test delivery

A signed test delivery is queued automatically. It carries the webhook.test event type, appears in delivery history, and can be replayed there. For a test on demand, use POST /api/webhooks/{id}/test.

Recipes

Receive and verify an HMAC webhook

Open Recipe

Body Params

A request to register a destination.

url

uri

required

length ≤ 2048

Where deliveries are sent. https:// only, and the host must resolve to a publicly routable address. Stored normalised, so a later read may differ in case from what was sent.

eventTypes

array of objects

required

length between 1 and 100

The event types to subscribe to. At least one is required, which is stricter than PATCH, where an empty array is a meaningful "subscribe to nothing".

eventTypes*

signatureScheme

string

enum

How deliveries to this registration are signed. Fixed at registration, since changing it would invalidate a secret already deployed; switching schemes is a delete and a fresh registration. HMAC_SHA256 uses a shared secret returned once at registration. JWS_ES256 is verified against the platform's published public key and involves no shared secret.

Allowed:

Headers

API-Version

string

required

^\d+\.\d+\.\d+$

The version of the Quant Flow API the request follows, as major.minor.patch (for example 1.0.0). The request is interpreted, and the response shaped, according to that version.

Idempotency-Key

string

required

Caller-supplied key making the write at-most-once. Required on every POST and PATCH; DELETE does not take one. A missing or blank header returns 400.
Replaying a key whose first request has finished returns that first response unchanged, with Idempotency-Replayed: true and the original Location where there was one. Sending a different body under the same key also returns the first response; the new body is ignored.
While the first request is still running, the same key returns 409 Conflict.
A key is only held once the request has succeeded. A write that fails releases it, so the same key can be used again for a retry.
A key is scoped to the caller and the operation: the organisation, the user, the HTTP method and the request path. The same value sent to a different endpoint, or by a different user in the same organisation, is a new request rather than a replay. There is no length limit.

Responses

201Registered. Location carries the path of the new registration. On the HMAC scheme the body contains the secret.

400The registration was refused before anything was stored.

401Returned once authentication is enforced, when the request carries no Authorization header or an unresolvable token. (planned — not returned today, see the API description.)

409The organisation already has a live registration for this URL, or an earlier request with the same Idempotency-Key is still running.

500An unexpected error occurred while handling the request.