DALP webhook event settlement.transfer.retracted reference

Reference for the DALP settlement.transfer.retracted webhook event that invalidates an earlier settlement transfer event after a chain reorg.

settlement.transfer.retracted tells a webhook consumer that an earlier settlement transfer event is no longer valid because a chain reorg invalidated the source log.

Use this event to reverse downstream settlement state created from the superseded event. The retraction is an event outcome signal, not a new settlement instruction. Verify the delivery before you apply the retraction. Match supersedes to the earlier event, then keep the retraction as the authoritative state.

Delivery contract

Field	Value
Event type	`settlement.transfer.retracted`
Version	`1`
Lifecycle state	`retracted`
Counter-signed receipt required	`true`
SDK type	`Webhook.SettlementTransferRetractedV1`

Related references:

idxr_settlement: the indexed settlement named by payload.settlementId.
idxr_transfer: the indexed transfer row for the event named by supersedes.

When to consume this event

Consume settlement.transfer.retracted when your integration records settlement transfer outcomes from DALP webhooks and needs to unwind a previously accepted event after a chain reorg. Typical consumers include settlement ledgers, reconciliation queues, notification systems, and exception dashboards that mirror settlement transfer status outside DALP.

Do not treat the retraction as a replacement transfer. The event says that the earlier event named by supersedes is no longer a valid outcome. Keep the original request or business instruction separate from the event outcome state.

Verify the webhook signature, timestamp, and event identifier before processing the payload. Then store evt_id, supersedes, payload.settlementId, payload.transactionHash, payload.reorgBlockNumber, and request.idempotency_key when present. Your consumer can use those fields to connect the retraction to the replaced event and avoid duplicate rollback work on retry.

See webhook idempotency and on-chain outcome for the broader pattern across final, retracted, and recalled lifecycle events.

Payload fields

Field	Type	Meaning
`settlementId`	String	Settlement identifier carried forward from the superseded settlement transfer event.
`chainId`	Integer	EVM chain identifier for the reorged event.
`transactionHash`	32-byte EVM hash	Transaction hash from the event that was invalidated by the reorg.
`supersedes`	Event identifier	Earlier event that this retraction replaces.
`reorgBlockNumber`	Integer	Fork block used to roll back indexed state and emit retractions.

Payload schema

{
  "type": "object",
  "properties": {
    "settlementId": {
      "type": "string"
    },
    "chainId": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "transactionHash": {
      "type": "string",
      "pattern": "^0x[a-fA-F0-9]{64}$"
    },
    "supersedes": {
      "type": "string",
      "pattern": "^evt_[a-zA-Z0-9]+$"
    },
    "reorgBlockNumber": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "settlementId",
    "chainId",
    "transactionHash",
    "supersedes",
    "reorgBlockNumber"
  ],
  "additionalProperties": false
}

TypeScript SDK example

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

const result = verifyWebhook({
  rawBody,
  headers,
  secret: process.env.DALP_WEBHOOK_SECRET!,
});

if (!result.ok) {
  throw new Error(`Webhook verification failed: ${result.code}`);
}

if (result.event.type === "settlement.transfer.retracted") {
  const event: Webhook.Event<"settlement.transfer.retracted"> = result.event;

  await markSettlementTransferRetracted({
    settlementId: event.payload.settlementId,
    supersededEventId: event.supersedes,
    reorgBlockNumber: event.payload.reorgBlockNumber,
    idempotencyKey: event.request?.idempotency_key,
  });
}

curl example

curl -X POST https://consumer.example.com/dalp/webhooks \
  -H "content-type: application/json" \
  -H "webhook-id: evt_docs_settlement_transfer_retracted_001" \
  -H "webhook-timestamp: 1778112000" \
  -H "webhook-signature: v1,docs-example-signature" \
  --data '{"evt_id":"evt_docs_settlement_transfer_retracted_001","type":"settlement.transfer.retracted","version":1,"lifecycle_state":"retracted","supersedes":"evt_docs_original_001","request":{"idempotency_key":"idem_01JZP7R5W8M9N0P1Q2R3S4T5"},"related":{"idxr_settlement":"idxr_settlement_example","idxr_transfer":"idxr_transfer_example"},"payload":{"settlementId":"stl_01JZP7R5W8M9N0P1Q2R3S4T5V6","chainId":537001,"transactionHash":"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","supersedes":"evt_finalSettlement001","reorgBlockNumber":18445201}}'

Version history

Version 1: Initial registry entry for settlement.transfer.retracted.

Deprecation

This event type is not deprecated.

Manifest

The machine-readable AsyncAPI entry is published in the DALP events manifest.

settlement.transfer.retracted

On this page