Compliance Events & Webhooks

Use these events to respond to screening results rather than polling.

Events

What you want to know	Event	Subscription
A transaction started screening, or was accepted, rejected, or frozen, for any check	`transaction.status.updated` (Webhooks v1: `TRANSACTION_STATUS_UPDATED`)	Webhooks v2
A Sumsub or GTR Travel Rule message needs more data, or is missing	`TRLink.RequiredActions`, `TRLink.NoTRMessage`	Compliance notification category

Outgoing and incoming transaction status changes, each sending a transaction.status.updated webhook event

Fireblocks sends transaction.status.updated at every status change, outgoing and incoming. For what each status and subStatus means, see Transaction states.

Webhooks v2: set up an endpoint and subscribe to the events you need. See Webhooks Overview.
Compliance notifications: in the Console, go to Settings > Notifications > Webhooks > Create Webhook, and select Compliance.

Then handle events reliably:

Verify each event’s signature before processing it. See Validating webhooks.
Acknowledge fast: return 200 right away and process asynchronously.
Do not rely on order: events can arrive out of order. Compare against the transaction’s current state.
Deduplicate on the notification id. For Travel Rule notifications, use destinationScreeningId when present; otherwise, use the envelope id.
Re-fetch before acting: read the current state from the API before bypassing, rescreening, unfreezing, or submitting a verdict.
Recover missed events: Webhooks v2 can resend notifications for up to 30 days. See Resending & troubleshooting webhook notifications.

Get full details on a status event

The data object of transaction.status.updated is the full transaction. Its subStatus does not say which check made the decision; read the complianceResults object, which carries every check’s result (provider, verdict, risk level) when the event includes it. amlScreeningResult is a legacy object; use complianceResults instead. For the raw provider payload, call GET /screening/transaction/{txId}. See Read the result for the fields.

app.post("/webhooks/fireblocks", async (req, res) => {
  res.sendStatus(200); // acknowledge first, then process
  const event = req.body;
  if (event.eventType !== "transaction.status.updated") return;

  const tx = event.data;
  if (tx.status === "REJECTED" && tx.subStatus === "REJECTED_AML_SCREENING") {
    const { data } = await fireblocks.compliance.getScreeningFullDetails({ txId: tx.id });
    await notifyCompliance(tx.id, data.aml?.verdict, data.aml?.risk);
  }
});

Travel Rule notifications (Sumsub, GTR)

These are audit-log notifications in the Compliance category (categoryId: "7"), not Webhooks v2 events. Tell them apart by note.messageType. note is a JSON-encoded string: parse it first. Only screeningMessage and messageType are always present. TRLink.RequiredActions: a Travel Rule message needs more data. Sent once per destination.

Field	Description
`trmId`	The Travel Rule message.
`customerIntegrationId`	The integration to call the resolve endpoints with.
`requiredActions`	The actions to take, each with a `type`, `description`, and `data`. Never empty.
`destinationScreeningId`	The destination this applies to, when the notification comes from destination screening. For tracking and deduplication only; to link a message to a destination, match by `amount` and `destination`.

TRLink.NoTRMessage: a transaction that needs a Travel Rule message has none. Includes the txId, destinationScreeningId, and destination details. Create and link a message, or submit a manual decision. For both flows, see Sumsub and GTR.

On the Help Center

There is no Help Center equivalent. In the Console, screening results appear in Transaction History > Transaction Details.

Get Started

Transactions

API Co-Signers

Webhooks

Workspace & Security

Identity & Compliance

Manage Wallets

Smart Contracts & Tokenization

Treasury & Trading

Gas Management

Payments

Embedded Wallets

Offchain Signing

Direct Custody Wallets

Integrations

Assets & NFTs

Canton

Key Link

Events

Get full details on a status event

Travel Rule notifications (Sumsub, GTR)

On the Help Center

​Events

​Subscribe

​Get full details on a status event

​Travel Rule notifications (Sumsub, GTR)

​On the Help Center

Events

Subscribe

Get full details on a status event

Travel Rule notifications (Sumsub, GTR)

On the Help Center