Webhooks creates webhook endpoints and shows the delivery history of each one. An endpoint is an HTTPS address on one of your systems, the consumer, and the platform sends it the organisation's platform events, such as a confirmed token transfer, as signed POST requests. The signature lets the consumer verify that a request came from the platform.
Configure an endpoint when another system needs to react to the organisation's platform events. An endpoint receives only the events that happen after it was created. To build the consumer, with its headers, signature check and event catalogue, see Receive DALP webhooks and the webhooks reference.
The “Webhooks” page opens with four cards, then the “Deliveries per hour, all endpoints” chart, then a table of endpoints.
The four cards are “Endpoints”, “Deliveries (24h)”, “Success rate (24h)” and “Failing endpoints”. Each endpoint row shows its “Status”, “Listening to” and delivery counts. Create endpoint sits at the top of the page.
Steps
Select Create endpoint
At the top of the page, select Create endpoint.
Enter the URL
Enter the Endpoint URL and, optionally, a “Display name” of up to 80 characters. The “Display name” field counts the characters as you approach that limit, and refuses a longer value instead of cutting it. The URL must use https and resolve to a public address unless the deployment operator has trusted it. A plain http:// URL that the operator has not trusted is refused under the field with “This server only accepts endpoint URLs that start with https://”, and nothing is created. When the deployment runs a built-in test receiver, “Use the DALP test receiver” fills in its address. That receiver answers 200 and stores nothing, so you can watch deliveries before your own consumer exists.
The “Create webhook endpoint” sheet, with the “Endpoint URL” field and “Use the DALP test receiver” under it, an optional “Display name”, and the “Subscriptions” the endpoint receives.
Choose subscriptions
Under Subscriptions, choose which events the endpoint receives. The checkboxes *.pending, *.provisional, *.final and *.retracted match the last part of an event name, and the form starts with *.provisional, *.final and *.retracted selected. transaction.request.* sends the five transaction request events and starts unchecked. A retracted event needs the state it retracts: if you select *.retracted, also select *.pending, *.provisional or *.final, or the platform refuses to save the endpoint.
The state checkboxes skip every event whose name ends in another word, such as funding., token. or operations.case.opened. Subscriptions lists every event they skip. To receive those, add them in Event names: search the published event catalogue, pick a family prefix, or type an exact name or a prefix such as token.corporate-action.*. The sheet refuses a name that matches no published event.
A broad subscription such as * also receives event types the platform adds later, and it sends every event the organisation produces to that URL, so the consumer must filter on its side. A narrow subscription keeps delivery volume down, but each new need means editing the endpoint's subscriptions, and an edit replaces the whole list.
Save the signing secret
Create the endpoint, then copy the signing secret, which starts with dalp_whsk_, from the “Save this signing secret now” dialog before you select I've saved it. The Console cannot show the secret again, and your consumer needs it to verify the signature on every delivery.
Review deliveries
The page shows delivery health across all endpoints for the last 24 hours. It loads the first 100 endpoints and says so when more exist. The list shows each endpoint with “Endpoint”, “Status”, “Listening to”, “Success (24h)”, “Delivered”, “Failed” and “Last delivery”, and the “URL” column is hidden by default. “Listening to” counts the event patterns the endpoint subscribes to, such as “1 pattern” or “3 patterns”. Hover the count to read the patterns.
Status reads “Enabled”, “Recovering”, “Auto-disabled” or “Disabled”.
Open an endpoint. The header holds the “Send test event” and “Edit” buttons and the Actions menu, which repeats both and adds “Replay events”, “Roll secret”, “Disable” or “Enable”, and “Delete”.
Overview shows the last 24 hours as the cards “Deliveries (24h)”, “Success rate (24h)”, “Response time (24h)”, “Waiting” and “Test deliveries (24h)”, with two delivery charts. “Response time (24h)” is the median time the consumer took to answer, with a line beneath it that gives the time 95 percent of attempts stayed within. “Waiting” counts the events queued or waiting to retry, up to 10,000: a larger backlog reads “10,000+”. Test deliveries are counted apart and stay out of the success rate.
Endpoint details shows the “ID”, “URL”, “Listening to”, “Payload” shape, whether “Signed receipts” are required, the “Event schema version”, the “Signing secret” version, the “Breaker” state, “Failures in a row:” and “Created”. The circuit breaker switches the endpoint off after 30 failed attempts in a row.
Event deliveries lists one row per event with its attempts nested under it, in the columns “Status”, “Event”, “Event ID”, “Attempts”, “Last response”, “Response time”, “Next retry” and “Time”. A “Live” indicator shows new events as they arrive, and “Load older” reads earlier ones.
The Status filter narrows the list to “Delivered”, “Failed”, “Retrying”, “Pending” or “Cancelled” events. “Response time” shows the time of each event's latest attempt, and an attempt with no recorded response time shows a dash.
When the endpoint requires signed receipts, Receipts lists each stored receipt with its “Verification” result.
Click an event to open its Webhook event sheet. It shows each attempt with its request, response and timings. It also shows the event's “Chain of custody”: one entry, called a hop, for each successful delivery, named “Sent to endpoint” with a hash of the exact body sent, and a “Root hash” computed over those hashes. Delivery statuses explains each status.
Send a test event
A test event is marked “test”, reaches the endpoint even while “Enabled” is off, and never moves the circuit breaker. Each API server accepts at most 10 test events a minute for an endpoint, and at most 100 for an organisation. Confirm that its row in Event deliveries reaches “Delivered” with a 2xx response from your consumer.
Resend a failed event
For one failed event, open its “Webhook event” sheet and select Resend. The platform adds one attempt to the same event with the same event ID, and earlier attempts keep their recorded outcome. Only the latest attempt of an event can be resent.
Replay events
To send past events again, choose Replay events in the “Actions” menu. The sheet offers two kinds of replay:
- Block range replays every event recorded for this endpoint in a range of blocks on the active network. Leave “To block” empty to replay up to the latest block with a recorded event. A range of more than 10,000 blocks asks you to confirm with “Replay anyway”.
- One event replays one event from the endpoint's recent deliveries.
Each replayed event gets a new event ID and is marked as a replay, so the consumer must deduplicate it on its payload identifiers rather than on the event ID. The platform refuses a replay while the endpoint is switched off or its circuit breaker is open, and an organisation can start at most 10 replays a minute on each API server. When the limit is reached the sheet reads “Replays are limited to 10 a minute: continue in a minute.”
On an endpoint whose breaker opened, a callout on “Overview” titled “DALP disabled this endpoint after repeated failures” offers Reactivate and replay failed events with the count of failed events. While the platform probes the endpoint it reads “DALP is probing this endpoint before it resumes deliveries”. The button reads “Reactivate” when no failed event is left to replay and “Replay failed events” with a count once the endpoint is enabled again.
Edit an endpoint
Select Edit. The “Edit endpoint” sheet reads “Change where events go, which events are sent, and how they are signed.” It holds:
- URL: if deliveries are waiting, a dialog asks before they go to the new URL.
- Subscriptions: which events the endpoint receives.
- Payload: “Thin” leaves out the fields the event catalogue marks as personal data, such as a transfer's
fromandtoaddresses. Amounts, token addresses and transaction hashes stay, and a transaction hash identifies the addresses on the network. “Full” includes personal data and needs the GDPR acknowledgement. Choosing it opens “Switch to fat events”, which lists every field that leaves DALP, and you confirm with “Acknowledge, switch to fat events”. - Require signed receipts: the endpoint must answer each delivery with a signed receipt. “Receipt timeout” sets how many seconds, from 1 to 60, the platform waits for a receipt before it marks the attempt as timed out and retries the event.
- Enabled: disabling cancels the deliveries still queued for the endpoint, and events that happen while it is disabled are not sent later.
Save the sheet. The Console confirms Endpoint saved. An edit of the subscriptions replaces the whole list.
If the endpoint changed after the sheet loaded it, the platform refuses your save, changes nothing, and the sheet shows “This endpoint changed while you were editing”. Any saved change triggers this: an edit by another administrator or by you in another tab, “Actions” › “Disable” or “Enable”, or an update through the Platform API. Rolling the secret, or the circuit breaker switching the endpoint off or back on, does not.
The Audit trail shows who changed the endpoint and its old and new values. Reloading replaces the edits you made in the sheet, so note the ones you want to keep first. Select Reload the saved endpoint. The sheet stays open with the endpoint as it is stored now. Make your changes again and save.
Roll the signing secret
Choose “Actions” › Roll secret.
In the “Rotate signing secret” sheet, select Rotate. The new signing secret, which starts with dalp_whsk_, appears once in the “Save this signing secret now” dialog: copy it before you select “I've saved it”, because the Console cannot show it again and the dialog stays open until you confirm. Rotation keeps the previous secret valid for 24 hours, and the platform signs each delivery with both secrets during that overlap. The “Previous secret” is retained only during the rotation overlap. A “Needs test” or “Safe” badge shows whether a delivery signed with the new secret has succeeded.
Revoke previous now ends the overlap early, but only after a delivery signed with the new secret has succeeded: send a test event under the new secret first. The previous secret then reads “Revoked”.
Disable or enable an endpoint
Choose “Actions” › Disable. The dialog titled “Disable” followed by the endpoint's name reads that new events skip this endpoint while it is disabled and are not sent later, and that deliveries still queued for it are cancelled. Enabling it again only delivers events that happen after that. The Console confirms “Endpoint disabled”.
Choose “Actions” › Enable to switch it on again, and the Console confirms “Endpoint enabled”.
Delete an endpoint
Choose “Actions” › Delete. The dialog “Delete this webhook endpoint?” reads that the endpoint stops receiving deliveries, including retries already scheduled, and that its delivery history stays available for the retention period. Select “Delete”, or “Cancel” to keep it. The Console confirms “Endpoint deleted”.
Delivery statuses
The platform records an event for each endpoint whose subscriptions match it. It retries a failed delivery for up to three days from when it recorded the event, with exponential backoff and jitter: each wait roughly doubles, with a random spread so that failing endpoints do not retry in step.
HTTP 408, 429 and 5xx responses, redirects and connection failures are retried, and a retryable failure moves the event to “Retrying”. Any other 4xx response stops delivery of that event. A terminal failure, or the end of the three-day retry window, moves the event to “Failed”. A 2xx response moves the event to “Delivered” unless the endpoint requires signed receipts.
On such an endpoint, a receipt that does not arrive in time moves a delivered event back to “Retrying”, and a receipt whose hash does not match moves it to “Failed”. An event appears in Event deliveries once the outcome of its first attempt is recorded, and an event still waiting when you turn off or delete its endpoint shows as “Cancelled”.
A webhook event ends as Delivered, Failed or Cancelled, or waits as Retrying, depending on the response, the retry window and its endpoint.
Troubleshooting
The signing secret was not saved
Choose “Roll secret” in the endpoint's “Actions” menu, then Rotate in the “Rotate signing secret” sheet. Copy the new secret from the “Save this signing secret now” dialog before you select “I've saved it”.
A rotated secret breaks signature verification
Rotation keeps the previous secret valid for 24 hours, and the platform signs each delivery with both secrets during that overlap, so a consumer that still verifies with the old secret keeps accepting deliveries. Update the consumer to the new secret before the 24 hours end. Revoke previous now ends the overlap early, but only after a delivery signed with the new secret has succeeded: send a test event under the new secret first.
An event never arrived and deliveries have stopped
Check the event's age against the three-day retry window. Once an event passes that window, or once a delivery fails in a way the platform treats as non-retryable, the platform stops automatic attempts. Read the last failure in the “Webhook event” sheet, fix the consumer, then use Resend or “Replay events”.
Deciding how broadly to subscribe an endpoint
A broad subscription such as * never needs revisiting when the platform adds an event type the consumer should know
about. It sends every event, so the consumer must filter on its side. A narrow subscription keeps delivery volume
down, but each new need on the consumer side means editing the endpoint's subscriptions. An edit replaces the whole
list.
The endpoint shows Auto-disabled
After 30 consecutive failed attempts, the platform opens the endpoint's circuit breaker and switches the endpoint off. Events that happen while it is off are not queued for it, and no replay can recover them later. The platform probes the endpoint and resumes deliveries on its own after two successful probes. The endpoint then reads “Recovering” until the next delivery succeeds. To resume at once, fix the consumer, then select Reactivate and replay failed events on the endpoint's “Overview” tab. It re-enables the endpoint and replays up to 10 of the failed events loaded in “Event deliveries”. Use “Replay events” for the rest.