[{"id":"/docs/concepts/events-out/webhook-delivery","type":"page","content":"Webhook Delivery","breadcrumbs":["Documentation","Concepts","Events out"],"url":"/docs/concepts/events-out/webhook-delivery"},{"id":"/docs/concepts/events-out/webhook-delivery-32","content":"Each delivery reaches your receiver as one POST request with a JSON body. Three of its headers follow Standard Webhooks, an open scheme with verification libraries in most languages: `webhook-id` identifies the message, `webhook-signature` holds the signature or signatures, and `webhook-timestamp` gives the signing time in whole seconds. The platform adds `webhook-delivery-id` for the individual attempt and `webhook-endpoint-id` for the endpoint it addressed.","type":"text","url":"/docs/concepts/events-out/webhook-delivery#receiving-verifying-and-answering"},{"id":"/docs/concepts/events-out/webhook-delivery-0","content":"Webhook Delivery signs each event, retries failures for three days and records every attempt, so your receiver needs no retry logic of its own.","type":"text","url":"/docs/concepts/events-out/webhook-delivery"},{"id":"/docs/concepts/events-out/webhook-delivery-86","content":"Transaction Lifecycle The states an instruction passes through inside the platform. A webhook is how an outside system hears about those state changes, and is not one of them.","type":"text","url":"/docs/concepts/events-out/webhook-delivery#related-concepts"},{"id":"/docs/concepts/events-out/webhook-delivery-58","content":"Sending a webhook and recording its outcome are separate effects. A process can stop after your receiver got the POST but before the attempt record is written, and recovery may repeat that send.","type":"text","url":"/docs/concepts/events-out/webhook-delivery#recovery-reuses-recorded-attempts"},{"id":"/docs/concepts/events-out/webhook-delivery-30","content":"Webhook Delivery keeps that work on the platform side. It owns the retry schedule, the per-endpoint circuit breaker and the attempt records an operator reads back when a receiver later disputes whether it was told.","type":"text","url":"/docs/concepts/events-out/webhook-delivery#why-a-notice-needs-its-own-delivery-system"},{"id":"/docs/concepts/events-out/webhook-delivery-61","content":"Webhook Delivery gives every registered endpoint its own circuit breaker, with three states: closed, open and half-open. It keeps one failing endpoint from consuming delivery capacity meant for every other receiver, and it lets recovery happen without an operator noticing and re-enabling the endpoint.","type":"text","url":"/docs/concepts/events-out/webhook-delivery#the-circuit-breaker-that-watches-endpoint-health"},{"id":"/docs/concepts/events-out/webhook-delivery-33","content":"Verify with a Standard Webhooks library rather than by hand, using the endpoint's signing secret, and let the library reject a timestamp outside its tolerance. The library accepts a five-minute spread between that timestamp and your clock, so keep the receiver's clock synchronised. The platform re-signs an envelope before an attempt once its timestamp has reached four minutes old, so a message that waited in backoff does not arrive already expired. While a signing secret rotates, `webhook-signature` holds one signature per secret, separated by a space, and verifying against any one of them is enough.","type":"text","url":"/docs/concepts/events-out/webhook-delivery#receiving-verifying-and-answering"},{"id":"/docs/api-reference/guides/webhooks","type":"page","content":"Receive webhooks","breadcrumbs":["Documentation","API reference","Guides"],"url":"/docs/api-reference/guides/webhooks"},{"id":"/docs/api-reference/guides/webhooks-27","content":"| Header              | Contents                                                                |\n| ------------------- | ----------------------------------------------------------------------- |\n| `webhook-signature` | The signature over `webhook-id`, `webhook-timestamp`, and the raw body. |","type":"text","url":"/docs/api-reference/guides/webhooks#verify-the-signature","table":"table-0"},{"id":"/docs/api-reference/guides/webhooks-43","content":"`POST /api/v2/webhooks/{webhookId}/secret-rotations` returns a new `signingSecret` and keeps the previous secret valid for 24 hours. During that overlap, the platform signs deliveries with both secrets, and `webhook-signature` holds both signatures. Store the new secret immediately, then accept either secret until `previousRevokesAt` passes.","type":"text","url":"/docs/api-reference/guides/webhooks#rotate-the-signing-secret"},{"id":"/docs/api-reference/guides/webhooks-52","content":"`DELETE /api/v2/webhooks/{webhookId}` switches the endpoint off permanently and cancels its queued deliveries, including scheduled retries. Its delivery history stays readable until the retention cleanup removes it.","type":"text","url":"/docs/api-reference/guides/webhooks#switch-off-or-delete-an-endpoint"},{"id":"/docs/api-reference/guides/webhooks-45","content":"`DELETE /api/v2/webhooks/{webhookId}/secret-rotations/previous` ends the overlap early. The platform refuses it until a delivery signed with the new secret has succeeded, so send a test event first.","type":"text","url":"/docs/api-reference/guides/webhooks#rotate-the-signing-secret"},{"id":"/docs/api-reference/guides/webhooks-41","content":"`POST /api/v2/webhooks/{webhookId}/test-events` queues a test event for one endpoint, whatever its subscriptions. The optional body field `eventType` names the event, and it defaults to `webhook.test.final`. The envelope carries `is_test: true` and the payload `{ \"test\": true }`, so your receiver can check its signature verification without acting on a real event.","type":"text","url":"/docs/api-reference/guides/webhooks#send-a-test-event"},{"id":"/docs/api-reference/guides/webhooks-46","content":"`PATCH /api/v2/webhooks/{webhookId}` changes `url`, `displayName`, `subscriptions`, `defaultPayloadShape`, `fatEventsAcknowledgment`, `counterSignedReceipts`, `receiptTimeoutSeconds`, `disabled` and `disabledReason`. Every field is optional, and the platform leaves an omitted field untouched. Supplying `subscriptions` replaces the full stored list. The subscriptions reference defines valid patterns.","type":"text","url":"/docs/api-reference/guides/webhooks#update-an-endpoint"},{"id":"/docs/api-reference/guides/webhooks-24","content":"The platform sends three Standard Webhooks headers and two DALP headers:","type":"text","url":"/docs/api-reference/guides/webhooks#verify-the-signature"},{"id":"/docs/changelog/dalp-3-0/webhooks","type":"page","content":"Webhooks","breadcrumbs":["Documentation","Changelog","DALP 3.0"],"url":"/docs/changelog/dalp-3-0/webhooks"},{"id":"/docs/changelog/dalp-3-0/webhooks-32","content":"Receive DALP webhooks →","type":"text","url":"/docs/changelog/dalp-3-0/webhooks#next-steps"},{"id":"/docs/changelog/dalp-3-0/webhooks-33","content":"Manage webhook endpoints →","type":"text","url":"/docs/changelog/dalp-3-0/webhooks#next-steps"},{"id":"/docs/changelog/dalp-3-0/webhooks-34","content":"Understand webhook delivery →","type":"text","url":"/docs/changelog/dalp-3-0/webhooks#next-steps"},{"id":"/docs/changelog/dalp-3-0/webhooks-20","content":"Each delivery follows the Standard Webhooks scheme. It carries a `webhook-id` header equal to the event's `evt_id`, a `webhook-timestamp` header and a `webhook-signature` header holding an HMAC-SHA256 signature over the id, the timestamp and the raw body. The TypeScript SDK checks all of it in one call and returns the typed event, or a failure code of `TIMESTAMP_SKEW`, `SECRET_MISMATCH` or `BODY_HASH_MISMATCH`. It refuses a timestamp more than five minutes away, and DALP signs a delayed retry again so it arrives inside that window.","type":"text","url":"/docs/changelog/dalp-3-0/webhooks#prove-an-event-came-from-dalp-before-acting-on-it"},{"id":"/docs/changelog/dalp-3-0/webhooks-13","content":"How DALP delivers a webhook and what happens when your URL fails.","type":"text","url":"/docs/changelog/dalp-3-0/webhooks#before-and-after"},{"id":"/docs/changelog/dalp-3-0/webhooks-14","content":"How DALP delivers a webhook and what happens when your URL fails.","type":"text","url":"/docs/changelog/dalp-3-0/webhooks#before-and-after"},{"id":"/docs/changelog/dalp-3-0/webhooks-28","content":"Nothing to do. Webhooks are an additional delivery channel, and integrations that poll the Platform API keep working as before.","type":"text","url":"/docs/changelog/dalp-3-0/webhooks#upgrading"},{"id":"/docs/console/organisation-settings/webhooks","type":"page","content":"Webhooks","breadcrumbs":["Documentation","Console","Organisation settings","Infrastructure"],"url":"/docs/console/organisation-settings/webhooks"},{"id":"/docs/console/organisation-settings/webhooks-68","content":"The delivery statuses of one webhook event.","type":"text","url":"/docs/console/organisation-settings/webhooks#delivery-statuses"},{"id":"/docs/console/organisation-settings/webhooks-69","content":"The delivery statuses of one webhook event.","type":"text","url":"/docs/console/organisation-settings/webhooks#delivery-statuses"},{"id":"/docs/console/organisation-settings/webhooks-23","content":"The Webhooks entry appears under Infrastructure only for those roles.","type":"text","url":"/docs/console/organisation-settings/webhooks#before-you-start"},{"id":"/docs/console/organisation-settings/webhooks-24","content":"Webhook management uses organisation permissions, not an on-chain contract role.","type":"text","url":"/docs/console/organisation-settings/webhooks#before-you-start"},{"id":"/docs/console/organisation-settings/webhooks-0","content":"Create webhook endpoints, choose their events, and inspect, resend and replay their deliveries in the Console.","type":"text","url":"/docs/console/organisation-settings/webhooks"},{"id":"/docs/console/organisation-settings/webhooks-20","content":"The \"Webhooks\" page opens with four cards, then the \"Deliveries per hour, all endpoints\" chart, then a table of\nendpoints.","type":"text","url":"/docs/console/organisation-settings/webhooks"},{"id":"/docs/console/organisation-settings/webhooks-70","content":"A webhook event ends as Delivered, Failed or Cancelled, or waits as Retrying, depending on the response, the retry window and its endpoint.","type":"text","url":"/docs/console/organisation-settings/webhooks#delivery-statuses"},{"id":"/docs/deployment/runbooks/webhook-deliveries-failing","type":"page","content":"Webhook deliveries failing","breadcrumbs":["Documentation","Deployment","Recover","Runbooks"],"url":"/docs/deployment/runbooks/webhook-deliveries-failing"},{"id":"/docs/deployment/runbooks/webhook-deliveries-failing-10","content":"A registered webhook endpoint stops receiving events it previously received.","type":"text","url":"/docs/deployment/runbooks/webhook-deliveries-failing#symptoms"},{"id":"/docs/deployment/runbooks/webhook-deliveries-failing-8","content":"Every check reads from the endpoint's delivery history: one row per event with its attempts nested under it, each attempt with its status, its failure class, and the response your consumer returned. In Console, open Organisation settings, then Webhooks, then the endpoint. The Event deliveries tab lists every event with its attempts, and clicking a row opens the Webhook event sheet with the failure class, the signed request headers, the response, and a ready-made repro command. The same history is available from the `dalp` command-line tool as `dalp get webhooks deliveries <webhookId>`, and over the webhook management endpoints.","type":"text","url":"/docs/deployment/runbooks/webhook-deliveries-failing"},{"id":"/docs/deployment/runbooks/webhook-deliveries-failing-0","content":"A webhook endpoint stops receiving events: the retry schedule, the automatic circuit breaker that pauses a failing consumer, and how deliveries recover.","type":"text","url":"/docs/deployment/runbooks/webhook-deliveries-failing"},{"id":"/docs/deployment/runbooks/webhook-deliveries-failing-7","content":"A registered webhook endpoint has stopped receiving some or all of its events. Open its delivery history: its shape tells you whether attempts keep failing, have stopped, or succeeded while your consumer disagrees. A webhook endpoint is a URL you register with a DALP instance so the platform pushes a signed HTTP request to it whenever a relevant event happens. It covers outbound webhook delivery from the platform to your consumer. Webhooks your instance receives from compliance providers are a different surface with their own management screens.","type":"text","url":"/docs/deployment/runbooks/webhook-deliveries-failing"},{"id":"/docs/deployment/runbooks/webhook-deliveries-failing-69","content":"If the attempt still fails after ten reruns, about eight and a half hours after the first, or cannot be completed at all, the platform marks that event as failed with the reason `attempt_workflow_died` and logs the error. The endpoint's later events then keep flowing. Replay the failed event with the webhook replay call.","type":"text","url":"/docs/deployment/runbooks/webhook-deliveries-failing#frequently-asked-questions"},{"id":"/docs/deployment/runbooks/webhook-deliveries-failing-42","content":"Platform policy. The platform checks endpoint address and HTTPS policy at registration and before each dispatch. A URL that fails those checks cannot be registered. The endpoint URL must resolve to a publicly routable address. A receiver on private address space fails that check until the operator adds its range to `global.dalpApp.config.webhooks.allowedTargetCidrs` in the deployment's Helm values. The URL must also use https. Both rules share one exception: an origin the operator lists in `DALP_WEBHOOKS_TRUSTED_DESTINATIONS`, for a private-network install, is exempt from the https requirement and the public-address check alike, so an endpoint on that list can use http:// or a private address. Both settings widen the delivery policy for every organisation on the instance, not only the endpoint you are fixing, and a trusted origin receives deliveries over plain HTTP. List only private receivers your own team runs. Never list a DALP origin or another internal service whose responses must stay private, because the delivery history records the response, so a webhook manager in any organisation could read it through a delivery. Tenant-facing APIs cannot add an origin to that list. Only an operator changing the deployment's configuration can. An attempt that fails either rule before dispatch sends nothing, records `TARGET_REFUSED`, and does not retry: correct the endpoint URL or the deployment's configuration, then use Resend for each affected event.","type":"text","url":"/docs/deployment/runbooks/webhook-deliveries-failing#checks"},{"id":"/docs/deployment/runbooks/webhook-deliveries-failing-62","content":"If events aged past the 3-day retry window, or failed terminally, replay them. Replay covers only events the platform recorded for this endpoint. Events raised while the breaker was open were never recorded for it, so no replay returns them: reconcile that window from the API, from the time the breaker opened until it closed. The webhook replay call re-queues either one event by its id or every matching event in a block range. Each replayed delivery is flagged as a replay in its envelope, so your consumer can tell it from a first delivery. Replay is refused while the endpoint is disabled or the breaker is open, so recover the endpoint first, then replay. Check the delivery history for events approaching the 3-day window rather than waiting for an alert.","type":"text","url":"/docs/deployment/runbooks/webhook-deliveries-failing#actions"},{"id":"/docs/api-reference/webhooks/consuming","type":"page","content":"Consuming events","breadcrumbs":["Documentation","API reference","Webhooks"],"url":"/docs/api-reference/webhooks/consuming"},{"id":"/docs/api-reference/webhooks/consuming-24","content":"The platform adds the headers `webhook-delivery-id` and `webhook-endpoint-id` to the three headers of the open Standard Webhooks specification: `webhook-id`, `webhook-timestamp` and `webhook-signature`. The `webhook-endpoint-id` header names your endpoint and stays the same for it. The setup guide lists every header.","type":"text","url":"/docs/api-reference/webhooks/consuming#identifiers-and-deduplication"},{"id":"/docs/api-reference/webhooks/consuming-52","content":"| Property | Resend                                                              | Replay                                      |\n| -------- | ------------------------------------------------------------------- | ------------------------------------------- |\n| Request  | `POST /api/v2/webhooks/{webhookId}/deliveries/{deliveryId}/retries` | `POST /api/v2/webhooks/{webhookId}/replays` |","type":"text","url":"/docs/api-reference/webhooks/consuming#resend-and-replay","table":"table-3"},{"id":"/docs/api-reference/webhooks/consuming-100","content":"`GET /api/v2/webhook-receipts` lists the stored receipts, and `GET /api/v2/webhook-receipts/{id}` reads one. Both need webhook management permission. A receipt submission for a delivery that did not require a receipt when the platform sent it answers status 404 with `WEBHOOK_DELIVERY_NOT_FOUND`.","type":"text","url":"/docs/api-reference/webhooks/consuming#counter-signed-receipts"},{"id":"/docs/api-reference/webhooks/consuming-125","content":"Webhook Delivery: the delivery model and endpoint recovery.","type":"text","url":"/docs/api-reference/webhooks/consuming#related"},{"id":"/docs/api-reference/webhooks/consuming-0","content":"How a receiver reads DALP webhook deliveries: outcomes, identifiers, ordering, retries, Resend, Replay, chain of custody, receipts and retractions.","type":"text","url":"/docs/api-reference/webhooks/consuming"},{"id":"/docs/api-reference/webhooks/consuming-49","content":"A run of failed attempts can also switch the endpoint off. After 30 consecutive failed attempts, test events excluded, the platform opens the endpoint's circuit breaker and switches the endpoint off. The platform queues no new events for an endpoint that is off, and no Replay recovers them later. It probes the endpoint and resumes delivery after two successful probes. Enabling the endpoint with `PATCH /api/v2/webhooks/{webhookId}` and `disabled: false` resets the breaker at once. The Webhook Delivery concept describes the circuit breaker in full.","type":"text","url":"/docs/api-reference/webhooks/consuming#retries"},{"id":"/docs/api-reference/webhooks/consuming-102","content":"Use the machine-readable event definitions or the SDK's `Webhook` types for each event's envelope and payload schema. Those schemas do not hold the consent field-path list.","type":"text","url":"/docs/api-reference/webhooks/consuming#payload-shape"},{"id":"/docs/api-reference/webhooks/consuming-82","content":"The platform signs each delivery over `webhook-id`, `webhook-timestamp` and the exact body, as the setup guide describes. A 2xx response records that your endpoint answered. A counter-signed receipt records your system's acknowledgement of the exact body, signed with the endpoint's webhook signing secret. The endpoint setting `counterSignedReceipts` enables this acknowledgement. Enable it when you must show that your system, not only a proxy in front of it, accepted the exact body. Your receiver then posts a receipt within the receipt window after each 2xx response, or the platform retries the event. After a successful attempt, the platform schedules a deadline for the receipt.","type":"text","url":"/docs/api-reference/webhooks/consuming#counter-signed-receipts"},{"id":"/docs/api-reference/cli/commands","type":"page","content":"CLI commands","breadcrumbs":["Documentation","API reference","CLI"],"url":"/docs/api-reference/cli/commands"},{"id":"/docs/api-reference/cli/commands-20","content":"| API call                                             | CLI command                                         |\n| ---------------------------------------------------- | --------------------------------------------------- |\n| `POST /api/v2/webhooks/{webhookId}/secret-rotations` | `dalp create webhooks secret-rotations <webhookId>` |","type":"text","url":"/docs/api-reference/cli/commands#the-verb-first-pattern","table":"table-1"},{"id":"/docs/api-reference/cli/commands-21","content":"| API call                                      | CLI command                                |\n| --------------------------------------------- | ------------------------------------------ |\n| `GET /api/v2/webhooks/{webhookId}/deliveries` | `dalp get webhooks deliveries <webhookId>` |","type":"text","url":"/docs/api-reference/cli/commands#the-verb-first-pattern","table":"table-1"},{"id":"/docs/api-reference/cli/commands-25","content":"Where the list and the single-item read differ by a trailing path parameter, the command declares both parameters, and only the trailing one is optional. Give it only the first argument and it sends the list request. Give it both and it sends the single-item request. `get webhooks deliveries <webhookId>` lists the deliveries of a webhook, and `get webhooks deliveries <webhookId> <deliveryId>` reads one. `get token-compliance modules`, `get system addon-access-managers proposals` and `create tokens corporate-actions commit` work the same way.","type":"text","url":"/docs/api-reference/cli/commands#the-verb-first-pattern"},{"id":"/docs/api-reference/cli/commands-19","content":"| API call               | CLI command               |\n| ---------------------- | ------------------------- |\n| `GET /api/v2/webhooks` | `dalp get webhooks index` |","type":"text","url":"/docs/api-reference/cli/commands#the-verb-first-pattern","table":"table-1"},{"id":"/docs/api-reference/guides/upgrade-to-3-2","type":"page","content":"Upgrade an integration to 3.2","breadcrumbs":["Documentation","API reference","Guides"],"url":"/docs/api-reference/guides/upgrade-to-3-2"},{"id":"/docs/api-reference/guides/upgrade-to-3-2-382","content":"| 3.1 operation                       | 3.2 operation                                 | Note |\n| ----------------------------------- | --------------------------------------------- | ---- |\n| `POST /webhooks/{id}/rotate-secret` | `POST /webhooks/{webhookId}/secret-rotations` |      |","type":"text","url":"/docs/api-reference/guides/upgrade-to-3-2#removed-v2-operations-and-their-successors","table":"table-4"},{"id":"/docs/api-reference/guides/upgrade-to-3-2-381","content":"| 3.1 operation                                | 3.2 operation                                            | Note |\n| -------------------------------------------- | -------------------------------------------------------- | ---- |\n| `POST /webhooks/{id}/revoke-previous-secret` | `DELETE /webhooks/{webhookId}/secret-rotations/previous` |      |","type":"text","url":"/docs/api-reference/guides/upgrade-to-3-2#removed-v2-operations-and-their-successors","table":"table-4"},{"id":"/docs/api-reference/guides/upgrade-to-3-2-247","content":"| 3.1 operation                                                                | 3.2 operation                                                                   | Note |\n| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---- |\n| `POST /compliance/providers/{providerId}/webhooks/{webhookId}/rotate-secret` | `POST /compliance/providers/{providerId}/webhooks/{webhookId}/secret-rotations` |      |","type":"text","url":"/docs/api-reference/guides/upgrade-to-3-2#removed-v2-operations-and-their-successors","table":"table-4"},{"id":"/docs/api-reference/guides/upgrade-to-3-2-243","content":"| 3.1 operation                                                        | 3.2 operation                                                              | Note                           |\n| -------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------ |\n| `POST /compliance/providers/{providerId}/webhooks/{webhookId}/pause` | `POST /compliance/providers/{providerId}/webhooks/{webhookId}/transitions` | Send the target state in `to`. |","type":"text","url":"/docs/api-reference/guides/upgrade-to-3-2#removed-v2-operations-and-their-successors","table":"table-4"},{"id":"/docs/api-reference/guides/upgrade-to-3-2-244","content":"| 3.1 operation                                                             | 3.2 operation                                                              | Note                           |\n| ------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------ |\n| `POST /compliance/providers/{providerId}/webhooks/{webhookId}/reactivate` | `POST /compliance/providers/{providerId}/webhooks/{webhookId}/transitions` | Send the target state in `to`. |","type":"text","url":"/docs/api-reference/guides/upgrade-to-3-2#removed-v2-operations-and-their-successors","table":"table-4"}]