POST /v1/webhooks

POST /v1/webhooks

Scope	Idempotency-Key	Operation ID
`webhooks.manage`	Required	`registerWebhook`

Subscriptions name catalogue events. The URL must be https with no credentials, and every address its host resolves to must be public: private, loopback, link-local and other special ranges are refused (VALIDATION_FAILED, detail.field: url). The URL is resolved again before every attempt. A new endpoint answers 201 with its signing secret, shown once; keep it to verify X-Intellisol-Signature: t=<unix>,v1=<hex>, which is HMAC-SHA256 over "<t>.<raw body>". With reference, the tenant's endpoint is updated (URL and subscriptions) and re-enabled if it was disabled (200, no secret). Deliveries are at least once with exponential backoff, ordering is not guaranteed (each body carries the job's event sequence), and an endpoint failing persistently is disabled automatically. Idempotency-Key required. Audited.

Request

Signed with your API credential: see Authentication.

Parameter	In	Required	Description
`Idempotency-Key`	header	Yes	One key per user intent, reused for every retry of that intent. See Idempotency.

Body

Field	Type	Required	Description
`reference`	string	No	Pattern `^WHK-[0-9A-HJKMNP-TV-Z]{8}$`.
`url`	string, uri	Yes	Pattern `^https://`. At most 2048 characters.
`subscriptions`	array of string	Yes	One of: `delivery.requested`, `delivery.assigned`, `rider.accepted`, `delivery.picked_up`, `delivery.on_the_way`, `delivery.arrived`, `delivery.delivered`, `delivery.cancelled`, `delivery.reassigned`, `delivery.failed`, `delivery.exception_raised`, `delivery.batched`, `delivery.unbatched`, `relay.requested`, `relay.claimed`, `relay.completed`, `relay.failed`, `payment.state_changed`, `partner.blocked`, `partner.reactivated`, `bulk.created`, `bulk.recipient_confirmed`, `bulk.quote_ready`, `bulk.confirmed`, `bulk.progress_updated`, `bulk.completed`, `bulk.cancelled`, `credential.revoked`.

Responses

200

Updated.

Field	Type	Required	Description
`reference`	string	Yes	Pattern `^WHK-[0-9A-HJKMNP-TV-Z]{8}$`.
`url`	string	Yes
`subscriptions`	array of string	Yes	One of: `delivery.requested`, `delivery.assigned`, `rider.accepted`, `delivery.picked_up`, `delivery.on_the_way`, `delivery.arrived`, `delivery.delivered`, `delivery.cancelled`, `delivery.reassigned`, `delivery.failed`, `delivery.exception_raised`, `delivery.batched`, `delivery.unbatched`, `relay.requested`, `relay.claimed`, `relay.completed`, `relay.failed`, `payment.state_changed`, `partner.blocked`, `partner.reactivated`, `bulk.created`, `bulk.recipient_confirmed`, `bulk.quote_ready`, `bulk.confirmed`, `bulk.progress_updated`, `bulk.completed`, `bulk.cancelled`, `credential.revoked`.
`status`	string	Yes	One of: `ACTIVE`, `DISABLED`.
`secret`	string	No	The signing secret, in the 201 answer only (shown once)

201

Registered; the secret is shown this once.

Field	Type	Required	Description
`reference`	string	Yes	Pattern `^WHK-[0-9A-HJKMNP-TV-Z]{8}$`.
`url`	string	Yes
`subscriptions`	array of string	Yes	One of: `delivery.requested`, `delivery.assigned`, `rider.accepted`, `delivery.picked_up`, `delivery.on_the_way`, `delivery.arrived`, `delivery.delivered`, `delivery.cancelled`, `delivery.reassigned`, `delivery.failed`, `delivery.exception_raised`, `delivery.batched`, `delivery.unbatched`, `relay.requested`, `relay.claimed`, `relay.completed`, `relay.failed`, `payment.state_changed`, `partner.blocked`, `partner.reactivated`, `bulk.created`, `bulk.recipient_confirmed`, `bulk.quote_ready`, `bulk.confirmed`, `bulk.progress_updated`, `bulk.completed`, `bulk.cancelled`, `credential.revoked`.
`status`	string	Yes	One of: `ACTIVE`, `DISABLED`.
`secret`	string	No	The signing secret, in the 201 answer only (shown once)