Receive DALP webhooks

OverviewCopy Anchor Link

Webhooks send DALP lifecycle events to an HTTPS endpoint your integration registers. This guide covers registration, the signed envelope, signature verification, secret rotation, and endpoint updates. The webhooks reference covers which events the platform sends and how to consume them.

DALP uses Standard Webhooks headers and signing. Verify the signature before you trust a delivery. Deliveries can repeat; the consumer contract defines the identifiers to store and deduplicate.

Register an endpointCopy Anchor Link

POST /api/v2/webhooks creates an endpoint. The URL must be a public HTTPS address unless the deployment operator has configured an exception for private-network receivers. The platform refuses private or loopback destinations without that exception. The webhook management API defines the complete request and response.

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 first response includes signingSecret. Store it immediately; a later endpoint read never returns it. Retrying the same registration body with the same Idempotency-Key returns the existing endpoint with signingSecret: null, not a second endpoint. A changed body under that key returns 409 WEBHOOK_IDEMPOTENCY_KEY_REUSED. A repeat while registration is still running returns 409 WEBHOOK_CREATE_IN_PROGRESS. If the original response was lost, read the endpoint and rotate its secret to obtain a new one.

When subscriptions is omitted, the platform applies the default subscriptions. Those patterns match event name suffixes, not lifecycle states. Check the events the defaults skip before choosing the full subscription list for your integration.

Every new endpoint starts with the thin payload shape, which removes personal data fields. To receive those fields, register the endpoint first, then update it to fat with the required acknowledgement. The payload shape contract defines that acknowledgement.

The event envelopeCopy Anchor Link

Every delivery contains 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 machine-readable event definitions and TypeScript SDK define the payloads. The hand-written event catalogue explains when each event is sent and what your receiver does with it.

Transaction lifecycle eventsCopy Anchor Link

To track an on-chain write from broadcast to its outcome, subscribe to transaction.request.*. The default subscriptions skip this family: the events have names such as transaction.request.confirmed, not names that end in .final.

The transaction request catalogue describes all five events, when they are sent, how operator retries produce new outcomes, and which fields a thin delivery omits. These events track the request, not the finality of a token movement.

Verify the signatureCopy Anchor Link

The platform sends three Standard Webhooks headers and two DALP headers:

Verify the exact raw body against your stored signing secret before you parse or trust the payload. The SDK's verifyWebhook helper accepts timestamps within five minutes of your clock by default. The platform re-signs a stored envelope when its signature is at least four minutes old. Use the five-minute receiver window; four minutes is the platform's refresh threshold. Keep your receiver's clock synchronized. The verifier is exported as verifyWebhook from @settlemint/dalp-sdk/verify-webhook.

Secret rotationCopy Anchor Link

A rotation returns a new signingSecret and keeps the previous secret valid for 24 hours. During that overlap, the platform signs deliveries with both secrets. Store the new secret immediately, then accept either secret until previousRevokesAt passes.

Rotation does not replay its original response for the same Idempotency-Key. Another rotation creates another secret and revokes any older previous secret immediately. After an uncertain rotation response, read the endpoint's secret versions before deciding whether to rotate again. A read returns version metadata, never secret material.

Update an endpointCopy Anchor Link

PATCH /api/v2/webhooks/{webhookId} changes url, displayName, subscriptions, defaultPayloadShape, counterSignedReceipts, or the endpoint's disabled state. Every field is optional; the platform leaves an omitted field untouched. Supplying subscriptions replaces the full stored list. The subscriptions reference defines valid patterns.

A switch to fat, or a subscription change on a fat endpoint, requires fatEventsAcknowledgment to cover every personal data field the resulting subscriptions imply. Payload shape changes affect new events only. The payload shape contract covers the fields and stored payloads.

Changing url retargets pending deliveries. Disabling the endpoint cancels its queued deliveries. The platform refuses either change while deliveries are pending unless you send ?acknowledgePending=true. A subscription-only change does not require that acknowledgement.

Next stepsCopy Anchor Link

• Retries defines response classes, backoff, and the retry window.
• Resend and replay covers recovery after an endpoint failure.
• Counter-signed receipts defines the optional signed acknowledgement.
• Errors covers the error envelope a failed webhook management call returns.