# Webhook events

Source: https://docs.settlemint.com/docs/events
Subscribe to DALP lifecycle events with AsyncAPI, signed webhooks, idempotent delivery, and typed SDK verification.



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

## Lifecycle [#lifecycle]

<Mermaid
  chart="`flowchart TD
P[pending<br/>(mempool, opt-in)] -->|tx mined within reorg window| PR[provisional<br/>(opt-in)]
PR -->|past reorg depth| F[final<br/>(default)]
F -->|reorg invalidates log| R[retracted<br/>supersedes=evt_abc]
F -->|operator action| C[recalled<br/>supersedes=evt_abc, reason=...]
R -. if both fire .-> C

classDef transient fill:#eef6ff,stroke:#5b8def,color:#13233a
classDef terminal fill:#f0f8f4,stroke:#41a66b,color:#102619
classDef superseding fill:#fff3e9,stroke:#d68636,color:#3b2110
class P,PR transient
class F terminal
class R,C superseding
`"
/>

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 [#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 [#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 [#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 [#idempotency]

DAPI `Idempotency-Key` caching and webhook reconciliation are intentionally decoupled. Read [Idempotency and on-chain outcome](/docs/events/idempotency-and-on-chain-outcome) before treating any cached mutation response as proof of final on-chain state.