Receive DALP webhooks

OverviewCopy Anchor Link

Webhooks send DALP lifecycle events to an HTTPS endpoint your integration registers. Use them to react to indexed transfers, issuance, identity registration, role changes, and later retractions or recalls. API reads provide the current indexed resource state when your integration needs to reconcile a delivery.

DALP uses Standard Webhooks headers and signing. Deliveries can repeat. Verify the signature, deduplicate the verified event identifier, and make downstream processing idempotent.

Register an endpointCopy Anchor Link

POST /api/v2/webhooks creates an endpoint. The URL must be a public HTTPS address; DALP refuses a private or loopback address so a misconfigured endpoint cannot be used to reach internal infrastructure.

curl -X POST "https://your-instance.example.com/api/v2/webhooks" \
  -H "X-Api-Key: sm_dalp_..." \
  -H "Idempotency-Key: webhook-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhooks.example.com/dalp",
    "displayName": "Settlement notifications"
  }'

The response includes the first signing secret. Store it immediately; a later read of the endpoint never returns the secret again. Check whether the endpoint was created before sending another create request: repeating the request can create a second endpoint and secret, even with the same Idempotency-Key.

The endpoint has these defaults:

• subscriptions defaults to *.provisional, *.final, *.retracted, and *.recalled. Keep *.provisional in your set: identity-registration and access-control events fire only at that lifecycle state, so an endpoint that drops it silently misses them.
• defaultPayloadShape defaults to thin, which strips personal data fields from the delivered payload. Request the full shape explicitly if your integration needs the fields thin strips.

The event envelopeCopy Anchor Link

Every delivery carries an event envelope with evt_id, type, version, lifecycle_state, related resource references, and a typed payload. Request correlation and replay metadata are included when applicable. The event catalog supplies complete schemas and examples for each event.

Lifecycle names do not imply one universal sequence. For example, DALP sends token.transfer.final only after the block that holds the transfer reaches the finality depth configured for the chain. Before that, token.transfer.provisional reports the transfer, and a reorg retracts it with token.transfer.retracted. Identity registration and role changes use provisional events. Subscribe to the event families your integration needs and process their superseding events.

Verify the signatureCopy Anchor Link

DALP signs every delivery per the Standard Webhooks specification and sends three headers:

DALP adds two more headers beyond the base specification: webhook-delivery-id, unique per delivery attempt, and webhook-endpoint-id, naming the endpoint the delivery targets.

Verify the signature against your stored signing secret before you trust the payload. The DALP SDK's verifyWebhook helper accepts a timestamp up to five minutes old by default, matching the Standard Webhooks specification. DALP itself re-signs a stored envelope once it is four minutes old, to reduce the chance that a delayed attempt reaches your verifier with an old signature. Implement a five-minute receiver window. The four-minute figure is the platform's pre-delivery refresh threshold, not the bound your verifier should use.

Secret rotationCopy Anchor Link

Rotating a signing secret keeps the previous secret valid for 24 hours, so a receiver that caches the secret does not reject deliveries signed during the rotation window. The new signingSecret appears only in the rotation response; a later read of the endpoint never returns secret material. Check the endpoint before sending another rotation request, because the same idempotency key does not guarantee the original rotation response. Store the new secret immediately, then verify with both secrets until previousRevokesAt passes.

RetriesCopy Anchor Link

A delivery that fails retries on an exponential backoff: a 30-second base delay, doubling each attempt, with random jitter between 0.7 and 1.3 times the computed delay so retries from many endpoints do not all land in the same second. DALP keeps retrying for up to three days from when the event was recorded, then stops. Each attempt times out after 20 seconds if your endpoint does not respond.

Whether a failure retries depends on what your endpoint returned:

Return 408 or 429 deliberately when your endpoint needs backpressure; every other 4xx tells DALP to stop trying that delivery.

Update an endpointCopy Anchor Link

PATCH /api/v2/webhooks/{id} changes url, displayName, subscriptions, defaultPayloadShape, or the endpoint's disabled state. Every field is optional; DALP leaves an omitted field untouched. Widening the payload shape to fat, whether by changing defaultPayloadShape directly or by changing subscriptions on an endpoint already set to fat, requires a fatEventsAcknowledgment naming every personal data field the resulting subscription set now implies.

A change to url or subscriptions can retarget deliveries DALP already queued under the endpoint's previous configuration. DALP refuses the update by default when deliveries are pending: send ?acknowledgePending=true to consent to the change reaching them. Any other value, including the literal string false, leaves the flag unset and the update rejected while deliveries remain pending.

Replay and retry deliveriesCopy Anchor Link

POST /api/v2/webhooks/{id}/deliveries/{deliveryId}/retries queues one more attempt for a delivery that already ran. The response's scheduled field comes back false when that delivery already sits in a terminal state DALP will not retry.

POST /api/v2/webhooks/{id}/replays is the replay step named in the retry table above. Send a block range (fromBlock, an optional toBlock, and chainId) or a single event id (evtId) to requeue the matching events at the endpoint. A replay creates a fresh envelope with a new evt_id and is_replay: true. Deduplicate attempts by event id, then use the stable domain identifiers documented on the event page to avoid applying an already-processed outcome again.

Next stepsCopy Anchor Link

• Idempotency and async settlement covers Idempotency-Key on the webhook endpoint create call.
• Errors covers the error envelope a failed webhook management call returns.