Webhook event integration overview

DALP events are the asynchronous integration surface for on-chain lifecycle changes. This page is the canonical event catalogue for docs links to /docs/events. Start here to connect the AsyncAPI manifest, event references, reconciliation rules, and webhook verification checklist.

Events fit systems that react to DALP activity after it happens, including audit trails, monitoring pipelines, webhook consumers, reconciliation jobs, and evidence exports.

API reads fit systems that need the latest indexed state for a known resource. Write responses and idempotency keys track request submission and replay safety, but they do not prove that an on-chain outcome is final.

Start with the event catalogue when you need to choose the message your integration should subscribe to. Start with the idempotency guide when you need to decide whether a cached write response, retry, or webhook delivery proves the final on-chain result.

Find the right event page

When to use events

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 consistent 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 through the webhook endpoint API 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. These rules can remove additional fields from fat payloads or hash leaf values inside thin payloads, but cannot re-add fields the thin shape strips.

Verify a webhook delivery before parsing it

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. The event-specific reference pages use the same verify-first pattern before narrowing to a typed event, so this checklist applies to generated examples such as token.transfer.final and settlement.transfer.retracted.

import { verifyWebhook } from "@settlemint/dalp-sdk";

export async function handleDalpWebhook(request: Request, secrets: readonly string[]) {
  const rawBody = await request.text();
  const headers = Object.fromEntries(request.headers.entries());
  const result = verifyWebhook({ rawBody, headers, secret: secrets });

  if (!result.ok) {
    return new Response("invalid webhook signature", { status: 400 });
  }

  const event = result.event;
  await recordDelivery(event.evt_id, event.lifecycle_state, event.type);

  return new Response("ok", { status: 200 });
}

Use this order in every consumer:

1. Read and store the raw request body before JSON parsing changes whitespace or byte order.
2. Verify webhook-id, webhook-timestamp, and webhook-signature with the endpoint signing secret or the active-plus-previous secret pair during rotation.
3. Reject failed verification before any event-specific processing.
4. Dedupe retries by the verified event identifier before updating an external ledger, case system, or evidence store.
5. Parse the typed event only after signature verification succeeds.

When you rotate an endpoint secret, pass both the active and previous secrets to verifyWebhook until the rotation overlap ends. DALP keeps the previous secret valid for 24 hours so already-enqueued deliveries can finish without opening a long-lived replay path.

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.