Webhook events

DALP events are the asynchronous integration surface for on-chain lifecycle changes. The AsyncAPI manifest is the canonical machine-readable registry, while these pages explain the event shapes and reconciliation rules used by external systems.

Lifecycle

If both retraction and recall apply to the same original event, recall wins. The retracted event is dropped and the recall remains the authoritative superseding event.

Shape

DALP webhook payloads use a thin envelope around a typed event payload. The envelope carries delivery identity, lifecycle state, related DALP references, replay metadata, and the original request idempotency key when the event originated from a DAPI mutation. The event payload carries the domain fields specific to the event type.

Thin vs fat payloads

Endpoints default to the thin payload shape: per-event personally-identifiable fields (wallet addresses, country codes, reason codes) are omitted from the signed payload before delivery. Subscribing to thin events keeps the platform aligned with EDPB Guidelines 02/2025 on blockchain personal data — consumers receive enough context to dereference indexed state via the API but no first-party PII leaves DALP without explicit consent.

Endpoints can opt into the fat shape via PATCH /v2/webhooks/{id} with a fatEventsAcknowledgment.fieldsAcknowledged body listing every <eventType>.<fieldPath> the operator confirms is acceptable to deliver. The dapp's Switch-to-fat dialog computes the required field list from the endpoint's subscriptions and the central PII map; sending an incomplete list returns WEBHOOK_FAT_ACK_INCOMPLETE (DALP-0517). Operator-configured payload_redactor_config rules layer on top of the thin baseline — they can remove additional fields from fat payloads or hash leaf values inside thin payloads, but cannot re-add fields the thin shape strips.

Signing

Every delivery includes webhook-id, webhook-timestamp, and webhook-signature headers. Verify the exact raw body bytes with verifyWebhook from @settlemint/dalp-sdk before parsing the event.

Idempotency

DAPI Idempotency-Key caching and webhook reconciliation are intentionally decoupled. Read Idempotency and on-chain outcome before treating any cached mutation response as proof of final on-chain state.