Webhooks and events

How a flow reports its own progress across three independent axes, and how to reconcile a completed payment against your records.

A flow reports progress through signed webhooks that fire at every lifecycle transition. Polling works too, but webhooks are the path that scales: a flow can sit in settlement for a while, and polling it is wasted work.

Every payload is HMAC-signed, so your backend can verify an event came from Dynamic before acting on it.

Three axes, three event types

A flow does not have one status. It has three, and they move independently. That is the single most useful thing to understand about the event model, because a flow can be finished on one axis and still in progress on another.

Event	Axis	Example progression
Execution updated	What the payer has done	initiated → source_attached → quoted → signing → broadcasted → source_confirmed
Settlement updated	What Dynamic has delivered	none → routing → completed
Risk updated	What compliance concluded	unknown → cleared

Each event carries both the previous and the new state, so your backend can react to a specific transition rather than re-deriving what changed.

Execution reaching source_confirmed does not mean the money has landed. Settlement can still be routing. Treat settlement as the axis that tells you a payment is done.

Reconciling a completed payment

When settlement reaches completed, the event carries the on-chain transaction hash that delivered the funds to your destination. Paired with the flow’s memo, that is everything needed to match a payment against an internal order or treasury record.

The same payload carries the destination chain name and ID, plus block explorer URLs, so you can link a customer straight to their transaction without assembling explorer URLs yourself.

Choosing webhooks or polling

Polling is simpler to stand up and fine for a prototype or a low-volume flow. Webhooks are the right default in production: they remove the latency of a poll interval, they cost nothing while a flow is idle, and they deliver the settlement transaction hash without an extra read.

Nothing stops you doing both. A webhook-driven backend that also reconciles by polling on a schedule is a reasonable belt-and-braces posture for payments.

Flow event payloads

Flow events send a state-transition payload, not the full flow object. Use the flowId with getFlow to fetch the full flow state. See the Flow API guide for details on each state.

flow.execution.updated · object

Occurs whenever a flow’s execution state changes. The payload includes previousState and newState: for example initiated → source_attached, signing → broadcasted, or broadcasted → failed. Possible execution states: initiated, source_attached, quoted, signing, broadcasted, source_confirmed, cancelled, expired, failed.

flow.settlement.updated · object

Occurs whenever a flow’s settlement state changes. Settlement tracks the post-broadcast movement of funds. data.additionalData identifies the destination chain the settlement lands on with chainName (for example SOL or EVM) and chainId (a string, for example "101"). When the new state is completed, it also includes settlementTxHash (the on-chain transaction hash that delivered the settled funds) and blockExplorerUrls (explorer links for that transaction). Possible settlement states: none, routing, bridging, swapping, settling, completed, failed.

flow.risk.updated · object

Occurs whenever a flow’s risk assessment state changes. Fired when risk screening transitions, for example unknown → pending → cleared. Possible risk states: unknown, pending, cleared, blocked, review.

Example Flow Event Payload

{
  "eventId": "2a92c161-3167-44ad-8fce-4c6cdaed8129",
  "messageId": "5a2a5360-bb7e-4ea6-9bd3-0146bf2f734f",
  "webhookId": "a86acea4-e050-4846-8e4f-0ae039f6e37c",
  "userId": "a5914498-7a8b-4c58-b04c-9624fef2897c",
  "externalUserId": "usr_abc123",
  "eventName": "flow.execution.updated",
  "environmentId": "123e4567-e89b-12d3-a456-426614174000",
  "environmentName": "live",
  "timestamp": "2026-06-15T12:00:00.000Z",
  "data": {
    "axis": "execution",
    "flowId": "fl_abc123",
    "previousState": "initiated",
    "newState": "source_attached",
    "timestamp": "2026-06-15T12:00:00.000Z",
    "additionalData": {
      "fromAddress": "0x3FcE1F4F28DbA209344072867134A3a7F547C7f1",
      "fromChainId": "1",
      "sourceType": "wallet"
    }
  }
}

Example Flow Settlement Completed Payload

{
  "eventId": "2a92c161-3167-44ad-8fce-4c6cdaed8129",
  "messageId": "5a2a5360-bb7e-4ea6-9bd3-0146bf2f734f",
  "webhookId": "a86acea4-e050-4846-8e4f-0ae039f6e37c",
  "userId": "a5914498-7a8b-4c58-b04c-9624fef2897c",
  "externalUserId": "usr_abc123",
  "eventName": "flow.settlement.updated",
  "environmentId": "123e4567-e89b-12d3-a456-426614174000",
  "environmentName": "live",
  "timestamp": "2026-06-15T12:00:00.000Z",
  "data": {
    "axis": "settlement",
    "flowId": "fl_abc123",
    "previousState": "settling",
    "newState": "completed",
    "timestamp": "2026-06-15T12:00:00.000Z",
    "additionalData": {
      "chainName": "SOL",
      "chainId": "101",
      "blockExplorerUrls": [
        "https://explorer.solana.com/tx/3Eru8qQQdM6zc4jYgaUZPMxQn6ZhBPzy9gJBzZUje45ufijNAFHMqZSDmxTitXQgp4px9xoLd6oP3BnhCK2t1QJZ"
      ],
      "completedAt": "2026-06-15T12:00:00.000Z",
      "settlementTxHash": "3Eru8qQQdM6zc4jYgaUZPMxQn6ZhBPzy9gJBzZUje45ufijNAFHMqZSDmxTitXQgp4px9xoLd6oP3BnhCK2t1QJZ"
    }
  }
}

Use settlementTxHash with chainName and chainId to reconcile the completed flow against the destination-chain transaction, and blockExplorerUrls to link your users straight to it. Pair the hash with the flow memo to match the settlement to an internal order or invoice.

Fields with nothing to report are omitted rather than sent as null. chainName and chainId are absent until the flow has a destination chain, and blockExplorerUrls is absent when the settlement has no transaction hash yet or the destination network has no configured explorer.

Exchange transfer events

user.exchangeTransfer.success · object

Occurs whenever an exchange transfer is successfully initiated. Is an ExchangeTransferResponse.

user.exchangeTransfer.failed · object

Occurs whenever an exchange transfer fails for any reason. Contains error details about the failure.

Legacy checkout events

Checkout transaction events apply to the legacy checkout system. For new integrations, use Fireblocks Flow and subscribe to flow.* events instead.

Checkout transaction events send a state-transition payload, not the full transaction. Use the transactionId with getFlow to fetch the full flow state.

checkout.transaction.execution.updated · object

Occurs whenever a checkout transaction’s execution state changes. The execution state tracks how the transaction is moving through the payment lifecycle: for example initiated, source_attached, quoted, signing, broadcasted, failed, cancelled, or expired.

checkout.transaction.settlement.updated · object

Occurs whenever a checkout transaction’s settlement state changes. The settlement state tracks the post-broadcast flow of funds: for example none, routing, bridging, swapping, settling, completed, or failed.

checkout.transaction.risk.updated · object

Occurs whenever a checkout transaction’s risk assessment state changes. Fired when risk screening transitions between states such as unknown, cleared, or blocked.

Example Checkout Event Payload

{
  "eventId": "2a92c161-3167-44ad-8fce-4c6cdaed8129",
  "messageId": "5a2a5360-bb7e-4ea6-9bd3-0146bf2f734f",
  "webhookId": "a86acea4-e050-4846-8e4f-0ae039f6e37c",
  "userId": "a5914498-7a8b-4c58-b04c-9624fef2897c",
  "externalUserId": "usr_abc123",
  "eventName": "checkout.transaction.execution.updated",
  "environmentId": "123e4567-e89b-12d3-a456-426614174000",
  "environmentName": "sandbox",
  "timestamp": "2023-10-26T14:30:59.210Z",
  "data": {
    "axis": "execution",
    "previousState": "initiated",
    "newState": "source_attached",
    "transactionId": "484e49ba-3026-4e2c-9bf0-ed98ae224833",
    "timestamp": "2023-10-26T14:30:59.210Z",
    "additionalData": {
      "fromAddress": "0x3FcE1F4F28DbA209344072867134A3a7F547C7f1",
      "fromChainId": "1",
      "sourceType": "wallet"
    }
  }
}

Next

Webhook setup

Configuring endpoints and verifying signatures.

Delivery best practices

Retries, idempotency, and signature verification.