DALP webhook event catalogue: triggers, states and actions

For each webhook event, the tables give its lifecycle state, when the platform sends it and what your endpoint does with it. The events for token sales, trading venues and XvP settlements are on Market and settlement events. Payload fields, schemas and examples are not here. They live in the machine-readable event definitions and in the Webhook types of @settlemint/dalp-sdk. Subscriptions, lifecycle states and consuming rules have their own pages.

In a State cell, beta is an event-contract maturity label. It is not a value of the envelope's lifecycle_state field.

Before using payload fields

New endpoints use thin payloads, which omit personal data fields. Some actions in the tables need fields that thin payloads remove, such as accountAddress, subjectAddress, confirmationId or statementId. Configure fat payloads and acknowledge the required fields before the platform records those events if your receiver needs those fields. The payload-shape rules describe this change. Replay sends the stored payload, so it cannot recover fields already removed from a thin event.

Find the event for your question

Question	Go to
Did a transfer settle, or did a chain reorganisation undo it?	Token
Did a mint or burn happen, or was an asset paused?	Asset
Was a corporate action announced or completed, a fee charged, or a document published?	Token
Was a holder's balance frozen or released, or did a provider return a verification verdict?	Compliance
Was a role granted or revoked, or is a time-bound role about to end?	Access control
Was an identity registered or recovered, or a claim issued or revoked?	Identity
Does an address need gas funding before a write can run?	Funding
Did a deposit or withdrawal change a custody participant's balance, or did a smart wallet change?	Custody
Does something need an operator, such as a reconciliation break or a parked bank credit?	Operations
Did a token sale open, take a purchase, pay a refund or close?	Primary market
Was an exchange-versus-payment settlement approved, executed, cancelled or expired?	XvP settlement
Did an order change, a trade settle, or a bust reverse a trade?	Trading venue
Is there a confirmation of a token movement for one wallet?	Reporting

Access control

An access manager is the contract that records which accounts hold which roles. A role change has no final event: apply it when the provisional event arrives, and undo it when the matching retracted event arrives. A chain reorganisation replaces recent blocks. After a chain reorganisation removes the block of a role change, the platform sends a retracted event only when it recorded a successful delivery of the provisional event. If your acknowledgement was lost, the platform can cancel the event and send no retraction. Reconcile an uncertain role against the current canonical transaction receipt and its logs. Retractions states the rule.

Event	State	Sent when	What to do
`access-control.role-granted.provisional`	`provisional`	The platform reads a role grant on an access manager in a block that has not reached chain finality.	Add the role for `accountAddress` on `accessManagerAddress`. A role applies to that access manager only, not to the account on other managers.
`access-control.role-granted.retracted`	`retracted`	A chain reorganisation removes the block of a role grant after the platform recorded a successful delivery of `access-control.role-granted.provisional` to your endpoint.	Remove the role that the event named in `supersedes` added.
`access-control.role-revoked.provisional`	`provisional`	The platform reads a role revocation on an access manager in a block that has not reached chain finality.	Remove the role for `accountAddress` on `accessManagerAddress`. Roles on other access managers stay as they are.
`access-control.role-revoked.retracted`	`retracted`	A chain reorganisation removes the block of a role revocation after the platform recorded a successful delivery of `access-control.role-revoked.provisional` to your endpoint.	Restore the role that the event named in `supersedes` removed.

A role granted with an expiry is time-bound: the platform revokes it at expiresAt. The role can be a token role, which names tokenAddress and account, or the organisation owner role, which names userId. Two events announce the end of a time-bound grant. The platform's expiry sweep sends them rather than a chain log, so they arrive as final without a provisional event. Match them by grantId. A token role revocation also produces access-control.role-revoked.provisional when the revoke lands on chain. An owner role goes out on the organisation's default chain, so an organisation with no default chain receives neither event for it.

Event	State	Sent when	What to do
`access-control.role-grant.expiring`	`final beta`	A time-bound grant ends within 24 hours. The platform sends the event once for each expiry time. Re-issuing the grant with a later `expiresAt` sends it again, and a grant shorter than 24 hours sends it on the next sweep. A grant that is already past its end when the sweep first sees it sends only `access-control.role-grant.expired`.	Warn the holder or the person who granted it, and re-issue the grant before `expiresAt` if the role must stay.
`access-control.role-grant.expired`	`final beta`	The platform revoked the grant at its expiry. The platform sends the event once for each revoked grant, with `revokedAt` set. A grant that was extended, made permanent or revoked through the platform sends no event.	Remove the role from your records for the holder named in the event.

Asset

Asset events report changes to a tokenised asset, read from chain logs. A block reaches chain finality once the chain head is the network's finality depth past it, as Lifecycle states defines. The platform sends a final asset event at that point and never retracts it.

Event	State	Sent when	What to do
`asset.burn.final`	`final`	Token units are burned from a holder on chain.	`token.transfer.final` also reports the burn. Match `transferSourceId` to that event's `source_id` and book the burn once.
`asset.created.final`	`final`	An asset factory deploys a new asset token, and the platform indexes the token for the first time.	Register the asset by `assetAddress`. The event reports no supply: each mint arrives as an `asset.issuance.final` event.
`asset.issuance.final`	`final`	New token units are minted to a recipient on chain.	`token.transfer.final` also reports the mint, with the all-zero address as sender. Match `transferSourceId` to that event's `source_id` and book the issuance once.
`asset.issuance.provisional`	`provisional`	The platform indexes a block that holds a mint of token units, before the block reaches chain finality.	`asset.issuance.final` confirms the mint. If a chain reorganisation removes the block, `asset.issuance.retracted` replaces this event.
`asset.issuance.retracted`	`retracted`	A chain reorganisation removes the block of a mint after the platform recorded a successful delivery of `asset.issuance.provisional` to your endpoint.	Reverse the issuance you recorded for the event named in `supersedes`.
`asset.pause.final`	`final`	A token contract logs a pause.	The pause already took effect on chain. Stop submitting transfers for the asset until `asset.unpause.final` arrives.
`asset.unpause.final`	`final`	A token contract logs an unpause.	Allow transfers for the asset again.

Compliance

Freeze events report that a holder's balance of an asset was frozen or released, and the platform reads them from the logs of the asset contract. The verification verdict event reports a connected provider's decision and has no chain log behind it.

Event	State	Sent when	What to do
`compliance.freeze.final`	`final`	The block that froze a holder's balance of an asset reaches chain finality. `scope` is `address` when the whole address is frozen and `amount` when a set number of token units is frozen.	Treat the freeze as confirmed: the platform does not retract a `final` event. Skip it if you already applied `compliance.freeze.provisional` with the same `transactionHash` and `logIndex`.
`compliance.freeze.provisional`	`provisional`	The platform reads a freeze on a holder's balance of an asset in a block that has not reached chain finality.	Apply the freeze. `compliance.freeze.final` confirms it after chain finality, and `compliance.freeze.retracted` replaces it if a chain reorganisation removes the block.
`compliance.freeze.retracted`	`retracted`	A chain reorganisation removes the block of a freeze after the platform recorded a successful delivery of `compliance.freeze.provisional` to your endpoint.	Reverse the freeze that the event named in `supersedes` applied.
`compliance.unfreeze.final`	`final`	The block that released a freeze on a holder's balance reaches chain finality. `scope` is `address` when a whole-address freeze is released and `amount` when a set number of token units is released.	Lift the freeze only on this event: the platform sends no `provisional` event for a release.
`compliance.verification-verdict.final`	`final beta`	The platform applies a connected provider's verdict on a subject, such as a know-your-customer (KYC) check, and completes any claim write the verdict needs. A verdict that the platform does not apply, such as an out-of-date one, sends nothing.	Read `status` for the verdict and `claimEffect` to see whether the platform issued a claim, revoked one or changed none. The claim change reaches you later as `identity.claim-issued.final` or `identity.claim-revoked.final`.

Bank rail

Subscribe to bank-rail.credit.* and bank-rail.cash-out.* to follow bank payments on your endpoint's System and chain. The default state subscriptions skip these names. Every event below has envelope state final and version 1. A bank recall is a credit status event, separate from the envelope's reserved recall lifecycle.

The Console's Payments tab lists every recall, including the partial ones that send no credit event, so read it when a recall changes a credit and no event arrives.

Amounts are decimal strings in the bank currency: "12.50" with currency: "EUR" means 12.50 EUR. occurredAt is the time the rail stored the milestone. A thin payload omits participantId. Approval identities, thresholds, park reasons, recovered amounts and write-down figures stay private in every payload shape.

Event	State	Sent when	What to do
`bank-rail.credit.admitted`	`final beta`	The rail first records a credit, with status `processing`. A returned payout's re-credit also sends this event.	Track the credit by `creditId`. `provenance.cashOutId` identifies a returned payout.
`bank-rail.credit.minted`	`final beta`	The credit's mint settles, with status `minted`.	Mark the client credit complete.
`bank-rail.credit.parked`	`final beta`	The credit enters status `held`. A retry that parks again sends another event.	Keep the credit open for resolution. A checker step while held sends no event.
`bank-rail.credit.allocated`	`final beta`	A held credit's allocation to a client settles, with status `allocated`.	Mark the held credit allocated to the client.
`bank-rail.credit.returned-to-payer`	`final beta`	The bank refunds the payer and any held tokens are burnt, with status `returned-to-payer`.	Close the credit as refunded.
`bank-rail.credit.cancelled`	`final beta`	A full bank reversal cancels a credit before minting, with status `cancelled`.	Close the unminted credit. No recalled event accompanies this cancellation.
`bank-rail.credit.recalled`	`final beta`	Completed recalls cover the whole credit, with status `recalled`.	Record `amount` as the completing reversal's bank amount. Earlier partial recalls send no credit status event. Read the recall records for the full history.
`bank-rail.cash-out.requested`	`final beta`	The rail records a cash-out, with status `requested`, before approval or escrow completes.	Track the request by `cashOutId`.
`bank-rail.cash-out.instructed`	`final beta`	The bank receives the payout instruction, with status `instructed`.	Track the payout as instructed. Settlement and an unbooked payout send no duplicate.
`bank-rail.cash-out.paid`	`final beta`	The payout's tokens are burnt, with status `paid`, including recovery after a released payout settles late or a direct move into re-crediting for a pending return.	Mark the payout paid. A returned event can follow.
`bank-rail.cash-out.released`	`final beta`	The rail releases the holder's tokens without completing the payout, with status `released` and a release `reason`.	Record the release. A late bank settlement can lead to a paid event after recovery and burn. Partial recovery and starting the release send no event.
`bank-rail.cash-out.returned`	`final beta`	The bank returns the payout and the rail admits its re-credit, with status `returned`.	Match the re-credit's admitted event by `provenance.cashOutId`. Further returns create new credits without repeating this cash-out event.

Mint approval, mint submission and resolution submission send no intermediate credit event. Cash-out events advance once through requested, instructed, paid and returned, or report released. A released request can later report paid after late settlement, full recovery and burn, then returned once its re-credit is admitted. Remove delivery duplicates by evt_id, and use source_id to identify the same occurrence across replays.

Custody

A System is an organisation's on-chain DALP deployment, and its account factory creates smart wallets, which are contract wallets. Custody events report those accounts, including changes to their signing rules, and the cash balances of custody participants. The account events reach only endpoints on the System that owns the account. The deposit, withdrawal and fee events give amount as a decimal string in base units, the smallest unit of the asset that assetKey names.

Event	State	Sent when	What to do
`custody.account-created.final`	`final`	A System's account factory creates a smart wallet, and its block reaches chain finality. The platform sends nothing when it cannot match the factory to a System.	Record `accountAddress` and its first owner, `ownerAddress`. `identityAddress` is `null` when the account has no identity bound at creation.
`custody.gateway-deposit.settled`	`final beta`	A deposit into a custody gateway settles on chain and the client holds the custody receipts. When the receipts wait for the custodian to accept the forwarded coins, the platform sends the event once the custodian confirms.	Credit the client by `depositId`. `forwardedTo` is `null` when the coins stayed with the gateway as funding. A reindex sends the same event again with the same id, so dedupe by the event id.
`custody.gateway-withdrawal.settled`	`final beta`	A withdrawal request on a custody gateway is claimed on chain: the coins are paid to the payout address and the custody receipts are burned. The client or the keeper claims it, and both send the event.	Close the request by `requestId`. `fee` is `null` when no fee applied. A reindex sends the same event again with the same id, so dedupe by the event id.
`custody.signer-changed.final`	`final`	The signing rules of a System smart wallet change: a signer is added or removed, a signer's weight or the signing threshold changes, or the owner is replaced. The platform sends one event for each change, once its block reaches chain finality.	Branch on `change`: `weight` is set only for `signer-weight-changed`, `threshold` only for `threshold-changed` and `previousSignerHash` only for `owner-changed`. A signer appears only as `signerHash`, the keccak-256 hash of the signer bytes.

Funding

A funding requirement records that an address needs more of the chain's native currency to pay gas, the fee for a transaction. The platform opens one when a write, a transaction it sends to the chain, pauses for lack of gas, and closes it when the address is funded or the wait ends. Match the events of one requirement by requirementId, and read requiredWei as an amount in wei, the smallest unit of the native currency. observedWei, when present, is the balance the platform read for the address: on funding.requirement.raised the balance when the requirement opened, on funding.requirement.resolved the balance that settled it.

Event	State	Sent when	What to do
`funding.requirement.expired`	`final`	A funding requirement ends unfunded: its deadline passes before the address holds the required amount, or the last write waiting on it is cancelled.	Treat the writes that waited on the requirement as not executed. Fund the address and submit them again.
`funding.requirement.raised`	`final`	A write pauses because an address that must pay gas cannot cover the cost. The platform opens one requirement for that address on that chain and sends this event once, even when more writes pause on the same requirement.	Fund `subjectAddress` with at least `requiredWei` by `expiresAt`. Keep the requirement open in your records until `funding.requirement.resolved` or `funding.requirement.expired` arrives.
`funding.requirement.resolved`	`final`	The platform sees that the address holds at least the required amount and resumes the writes that waited on the requirement.	Close the requirement that you opened for the earlier `funding.requirement.raised` event. The waiting writes continue without further action.

Identity

Each System, an organisation's on-chain DALP deployment, has an identity registry that links account addresses to identity contracts, which hold the claims about each account. These events report changes to registry entries and to claims on registered identities. The platform sends a final identity event after chain finality and never retracts it.

Event	State	Sent when	What to do
`identity.claim-issued.final`	`final`	A claim is added to a registered identity, or changed. The platform sends one event for each System whose identity registry holds the identity.	`change` is `added` for a new claim and `changed` for an update to one. Use `claimId` to identify the claim. The event has no claim data.
`identity.claim-revoked.final`	`final`	The identity removes a claim, or its issuer revokes it. The platform sends one event for each System whose identity registry holds the identity.	`change` is `removed` when the identity removed the claim and `revoked` when the issuer revoked it. Use `claimId` to find the claim in your records.
`identity.registration.provisional`	`provisional`	The platform reads an account address being registered in a System's identity registry, as active or pending, in a block that has not reached chain finality. It sends nothing when a pending registration is accepted later.	Record the registration as unconfirmed, and read `status` to tell an active registration from a pending one. `identity.status.final` confirms it after chain finality.
`identity.registration.retracted`	`retracted`	A chain reorganisation removes the block of a registration after the platform recorded a successful delivery of `identity.registration.provisional` to your endpoint.	Remove the registration you recorded for the event named in `supersedes`.
`identity.status.final`	`final`	A registration in a System's identity registry is added, accepted after it was pending, moved to a replacement identity contract, removed, or recovered to a new wallet after the account's wallet is lost.	`change` is `registered`, `accepted`, `identity-replaced`, `removed` or `recovered`, and `status` is the resulting `pending`, `active` or `removed`. After a recovery, `accountAddress` is the new wallet and `previousAccountAddress` is the lost one.

Operations

An operations case records a problem that the platform cannot resolve automatically, for example a reconciliation break between a bank statement and token supply, or a bank credit that the bank rail parked. An operator acknowledges the case and resolves it, or the platform resolves it when the problem clears. A case that is not resolved by expiresAt is expired, and no event reports that. Two kinds belong to the custodian watch: custodian-privileged-action, for a privileged action by a wallet outside the custodian's organisation on a token it custodies, and custodian-upgrade-notice, for an upgrade scheduled for a factory whose tokens it custodies. Custodian watch describes both. Match the events of one case by caseId. Each event belongs to the chain in chainId. If chainId is null, the case names no chain and the event belongs to the organisation's default chain. A thin delivery omits participantId, accountRef, detail and resolvedBy.

Event	State	Sent when	What to do
`operations.case.acknowledged`	`final beta`	An operator acknowledges an open case. The platform sends the event once for each case.	Mark the case as being worked on. Read `acknowledgedAt` for the time of the acknowledgement.
`operations.case.opened`	`final beta`	The platform opens a case. The platform sends the event once for each case. A new problem of the same kind for the same subject adopts the existing case, open or resolved, and sends no event.	Route the case to your operators by `kind` and `severity`. Keep the case open in your records until `operations.case.resolved` arrives or `expiresAt` passes.
`operations.case.resolved`	`final beta`	An operator resolves the case, or the platform resolves it when the problem clears. The platform sends the event once for each case.	Close the case in your records. `resolvedBy` identifies the operator, or the platform service that resolved the case.

Reporting

Reporting events tell you what the platform recorded in its reporting store. reporting.confirmation-created.final confirms a token movement for one wallet, and the platform sends it only to endpoints of an organisation with a member who holds the wallet or signs for it, once the block reaches chain finality. The other reporting events go to every endpoint of the organisation.

Event	State	Sent when	What to do
`reporting.confirmation-created.final`	`final`	A mint, burn or transfer moves tokens in a wallet. The platform confirms each wallet affected: a transfer between two wallets confirms both, and a transfer to the same wallet confirms it once.	Fetch the confirmation by `confirmationId` from the reporting confirmations endpoint of the Platform API, which returns not found for a wallet that is not the caller's. A `thin` payload omits `confirmationId`, so this needs a `fat` payload.
`reporting.filing.deadline-warning`	`final beta`	A regulatory filing enters its configured deadline warning window without a submission. The platform emits one event for the filing period.	Read the filing period through the reporting endpoint of the Platform API and begin the required submission work.
`reporting.filing.sla-breached`	`final beta`	A regulatory filing misses its acknowledgement SLA or calendar deadline. The platform emits one event for the filing period and event kind.	Read the filing period through the reporting endpoint of the Platform API and handle the overdue filing.
`reporting.mirror-movement.final`	`final beta`	A settled movement on a mirror token: a venue fill, the bust of a settled trade, a mint, a burn or a corporate-action movement. Sent once per movement when the day's settlement feed is first recorded, after the day closes in the token's cut-off timezone. The parties are OnchainID addresses, never personal data.	Book the movement at the custodian or registrar. `movementId` is stable, so a repeated delivery is the same movement. A `thin` payload omits `fromIdentity` and `toIdentity`, so this needs a `fat` payload.
`reporting.statement-ready.final`	`final beta`	The platform records a client statement for one wallet and period, as a scheduled statement, a contract note or an on-demand statement. Sent once, the first time the statement is recorded. A contract note the platform amends in place is not re-announced.	Read the statement through the reporting statements endpoint of the Platform API, then download each format the event's `formats` lists with the statement's download endpoint. A `thin` payload omits `statementId`, so this needs a `fat` payload.

Token

The platform reads transfer and fee events from chain logs. It sends a coupon claim or maturity redemption event for each claim or redemption log once the log's block reaches chain finality, and it records corporate action and document events itself, with no chain log behind them. A corporate action is a scheduled change to a token and its holders' positions, such as a dividend, a coupon or a stock split. A mint or burn also produces the transfer events, with the all-zero address as sender or recipient.

The token.transfer.provisional, token.transfer.retracted, asset.issuance.* and asset.burn.final events, and version 2 of token.transfer.final, carry occurredAt, the time of the block that holds the movement, so a ledger can post the movement on the right date from the event alone. A token that keeps a register books each movement as a numbered line with a register reference, the identifier the registrar files it under. When a movement is booked as one of those lines, the event also carries registerLine with lineId, registerReference and, for a line that corrects an earlier one, correctsLineId. A movement that the platform cannot pair with exactly one booked line carries no registerLine. A mint or burn of a mirror token carries externalReference, the custodian or registrar transaction id sent with the mint or burn. Events stored before these fields existed have none of them.

Event	State	Sent when	What to do
`token.corporate-action.announced`	`final beta`	A corporate action is cleared for execution: an approver signs it off, or the action needs no approval.	Read the action's record through the corporate actions endpoint of the Platform API. The event names the action, the token and the action type only.
`token.corporate-action.completed`	`final beta`	A corporate action finishes executing and reaches the completed state.	Read the final record through the corporate actions endpoint of the Platform API. A completed action cannot be aborted, so no retraction follows.
`token.corporate-action.paid`	`final beta`	A cash dividend, a distribution or a coordinated distribution that pays in cash reaches the completed state. The platform sends it with `token.corporate-action.completed`.	Use it to separate cash payouts from other completed actions. `totalAmount` is what holders are entitled to, in base units of `denominationAddress`. A claim-based payout moves that cash later, as holders claim. Other action types, and payouts made in kind rather than in cash, send only `token.corporate-action.completed`.
`token.corporate-action.retracted`	`final beta`	A corporate action that was approved, or needs no approval, is aborted before it completes. An action that was denied, expired or still awaiting approval sends nothing.	Match on `corporateActionId` to cancel what you expected from `token.corporate-action.announced`. This event has no `supersedes` and can arrive without an earlier announcement.
`token.coupon-claim.final`	`final beta`	A bond holder claims coupon cash from a fixed treasury yield feature or a legacy fixed yield schedule, and the claim's block reaches chain finality.	Book the cash paid to the holder. `amount` is in base units of `denominationAddress` and can be less than the sum of the periods from `fromPeriod` to `toPeriod`. `claimId` is `<blockNumber>:<logIndex>`. Converting yield into tokens sends no event, and claims that reached finality before the platform started sending this event have none. A `thin` payload omits `holder`.
`token.document.published`	`final beta`	A document upload is confirmed with `holders` visibility, and each replacement version sends its own event. Other visibility levels send nothing.	Fetch the file through the documents endpoints of the Platform API, which apply the caller's visibility. The event names the document, its type, its title and its publish time only.
`token.fee-period-close.final`	`final beta`	A token's fee accounting feature closes a fee period for a recipient. A close with a zero amount sends nothing.	Use it to end an accrual period: `token.fee.final` events with `basis` `accrued` since the previous close belong to this period.
`token.fee.final`	`final beta`	A token charges a fee: a fee feature collects or accrues it, or a fund collects its management fee. A fee of zero sends nothing.	A management fee or an assets-under-management fee mints the fee to the recipient, so `asset.issuance.final` and `token.transfer.final` also report it. Post the fee once, and read `basis` for `collected` or `accrued`.
`token.maturity-redemption.final`	`final beta`	A holder redeems matured bond tokens for cash from a maturity redemption feature or a legacy bond, and the redemption's block reaches chain finality.	Book the cash paid to the holder. `amount` is in base units of `denominationAddress` and `tokenAmount` is the redeemed tokens in the token's base units. A custodian that redeems several holders in one transaction sends one event for each holder. `redemptionId` is `<blockNumber>:<logIndex>`. Redemptions that reached finality before the platform started sending this event have none. A `thin` payload omits `holder`.
`token.transfer.final`	`final`	The platform indexes a transfer, mint or burn of a token.	Treat the movement as confirmed: a chain reorganisation never retracts version 2, and a chain reorganisation that removes the block before finality cancels the event unsent. A transfer that moves one leg of a venue trade also carries `venueTrade`, with `tradeId`, `marketId`, `venueAddress` and `leg`, which is `base`, `quote` or `fee`. The field is absent on every other transfer, and `tradeId` is `null` for a fill recorded before venues emitted trade ids. The platform sends this event in version 2 only. Version 1 went out when the block was included.
`token.transfer.provisional`	`provisional`	The platform indexes a block that includes a transfer, mint or burn of a token, before the block reaches chain finality.	`token.transfer.final` confirms the movement. If a chain reorganisation removes the block, version 2 of `token.transfer.retracted` replaces this event.
`token.transfer.retracted`	`retracted`	A chain reorganisation removes the block of a transfer, mint or burn after the platform recorded a successful delivery of the event it supersedes to your endpoint.	Reverse the record for the event named in `supersedes`, and branch on the envelope `version`. Version 2 replaces a `token.transfer.provisional` event, and version 1 replaces a version 1 `token.transfer.final` event. The platform sends `token.transfer.final` in version 2 only.

Transaction request

A transaction request is one on-chain write that the platform accepts and tracks. These events report the request's progress, not the finality of a token movement. Each event reaches the organisation and chain of the request. Match events by transactionId, and use the asset and token events to record movements.

Event	State	Sent when	What to do
`transaction.request.broadcast`	`pending`	The request enters a broadcast state with a transaction hash.	Store the hash and mark the request as awaiting an outcome. Do not book a token movement from this event.
`transaction.request.cancelled`	`final`	The request reaches `CANCELLED`.	Mark the request as cancelled. Read the transaction request record if you need the reason.
`transaction.request.confirmed`	`final`	The request reaches `COMPLETED`.	Mark the request as complete. Match the token or asset events before recording the resulting movement.
`transaction.request.dead-lettered`	`final`	The request reaches `DEAD_LETTER`.	Read the transaction request and its `mayStillLand`. While it is `true`, do not resend the call: hold the request open and wait for `transaction.request.confirmed`, `transaction.request.failed` or `transaction.request.cancelled` with the same `transactionId`. When it is `false`, the call did not land and the request does not settle by itself: ask an operator to close it, or send the call again with a new idempotency key.
`transaction.request.failed`	`final`	The request reaches `FAILED`.	Mark the request as failed and read the transaction request record for details. An operator can retry it, so another outcome can follow.

The final state of transaction.request.confirmed and the other outcome events means the request has its outcome. It does not mean the block is final on the chain. transaction.request.confirmed goes out once the platform's indexer has processed the block that holds the transaction, for direct wallet writes and for account abstraction writes alike. A chain reorganisation after that point can still remove the transaction, so wait for the token or asset events before you treat a movement as final. A transaction.request.dead-lettered event is the one exception while its transaction request shows mayStillLand: true: the event is final for the queue, but a later outcome event with the same transactionId can still follow.

The platform records the event together with the state change. Setting a request to the state it already holds sends nothing. Leaving the broadcast states and entering them again with a hash sends another broadcast event. Replacing a hash while confirming sends nothing. A request that fails, is retried by an operator, and fails again sends two failed events with different source_id values.

One request can send transaction.request.failed and then transaction.request.cancelled, when it is cancelled after it failed. A dead-lettered request can send another outcome later, as the transaction request table describes. Treat the latest outcome as the current one, and read the record before you retry or refund on a failed event.

A thin delivery omits fromAddress, errorMessage, and revertReason. The platform limits the two error fields to 1,024 characters. Read the full record with GET /api/v2/transaction-requests/{transactionId}.

The default subscriptions skip all five events. Use transaction.request.*, transaction.*, exact names, or *, as the subscriptions reference describes.

Test event

webhook.test.final is the default test event. The platform sends a test event only when someone requests one for an endpoint, from the Console or with POST /api/v2/webhooks/{webhookId}/test-events. It reaches that endpoint whatever its subscriptions, with lifecycle_state final, is_test set to true and the payload { "test": true }. Use it to check your signature verification, and never act on it as a business event. The setup guide states its limits.

Reserved names

These event names are registered, but no action in the platform sends them.

Event	Status
`compliance.freeze.recalled`	Reserved. No action sends this event. An exact subscription is accepted.
`settlement.transfer.retracted`	Reserved. No action sends this event. An exact subscription is rejected.
`token.transfer.pending`	Reserved. No action sends this event. An exact subscription is rejected.

Market and settlement events: the events of token sales, trading venues and XvP settlements.
Subscriptions: the patterns that select events, and the events the default subscriptions skip.
Lifecycle states: what each state means, with worked sequences.
Consuming webhooks: identifiers, deduplication, ordering, retries and retractions.