Webhook events

DALP events are the asynchronous integration surface for on-chain lifecycle changes. This page is the canonical event catalogue for docs links to /docs/api-reference/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 pageCopy Anchor Link

An issuance or burn event carries transferSourceId, the source_id of the token.transfer.final event for the same movement, so a ledger that subscribes to both books the movement once. compliance.freeze.recalled has no producer yet: its recallable compliance.freeze.provisional base is live, and the tenant recall action is still to come.

token.transfer.pending and settlement.transfer.retracted are deprecated. Neither has a producer: the indexer observes transfers after inclusion, and the settlement retraction has no source event. New exact-name subscriptions are rejected. Stored events remain decodable; use token.transfer.provisional for an included transfer before finality.

When to use eventsCopy Anchor Link

LifecycleCopy Anchor Link

Version 1 of token.transfer.final was emitted at inclusion and remains decodable for stored deliveries. A reorg still retracts a delivered version 1 final event and cancels an undelivered one. New transfers use a provisional event at inclusion and version 2 of the final event after the configured reorg depth. A reorg retracts a delivered provisional observation, never a version 2 final event.

ShapeCopy Anchor Link

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 Platform API mutation. The event payload carries the domain fields specific to the event type.

Thin vs fat payloadsCopy Anchor Link

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. Thin payloads reduce the personal fields disclosed through webhooks. Review each event schema and your endpoint settings against your data-protection requirements; the payload shape alone does not establish compliance.

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 Console'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 itCopy Anchor Link

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 token.transfer.retracted.

The following integration skeleton is illustrative. Implement recordDelivery as an idempotent write in your own system.

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

export async function handleDalpWebhook(request: Request, secrets: readonly string[]) {
  const rawBody = await request.text();
  const headers = Object.fromEntries(request.headers.entries());
  const result = await 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.

IdempotencyCopy Anchor Link

Platform API 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.