Canton Transaction Webhooks

A Canton integration is a webhook consumer first. An inbound offer is a status update on a transaction you never created, so there is nothing to poll for until the webhook fires. Fireblocks delivers these to the endpoint you register. You implement the receiver. The envelope is the standard Fireblocks webhook envelope, not a Canton-specific one, and the data object is the standard transaction notification. The only Canton-specific thing on the wire is the cantonDetails key on data.

Which event fires

Only TRANSACTION_STATUS_UPDATED carries cantonDetails. A Canton integration can discard every other event type at the front door.

Field	Type	Description
`type`	string	Always `TRANSACTION_STATUS_UPDATED`.
`tenantId`	uuid	The Fireblocks workspace the notification belongs to. Verify it against your own workspace ID rather than trusting the delivery URL.
`timestamp`	int64	When Fireblocks emitted the notification, in epoch milliseconds. Not a sequence number.
`data`	object	The transaction as of this notification.

Route an incoming notification

1. type == TRANSACTION_STATUS_UPDATED
2. read data.cantonDetails
3. no cantonDetails            → not a Canton transaction, ignore
4. cantonDetails.call          → an outgoing call of yours progressed
5. cantonDetails.settlement    → a venue settled an allocation you had locked
6. cantonDetails.offerResponse → offer conversation:
     availableResponses non-empty → answer it
                                    POST /v1/operations/canton/offers/{data.id}/responses
     availableResponses empty     → do not post; follow originalTransactionId if set

To answer in step 6, call Answer an offer with data.id as offerId. Step 4 covers calls you submitted with Make a Canton call. Both are covered end to end in Write Canton Transactions.

Step 6 is the answerability rule. Branch on availableResponses, never on subStatus. Examples 1 and 4 below share status: CONFIRMING and subStatus: PENDING_RECEIVER_APPROVAL, and only one of them is answerable.

The five states to tell apart

1. Actionable offer
2. Response in flight
3. Allocation locked
4. Linked leg
5. Settlement receipt

An inbound DTCC end-investor onboarding offer. availableResponses carries both DTCC values, so this transaction ID is the one to answer.

{
  "type": "TRANSACTION_STATUS_UPDATED",
  "tenantId": "d41b6f28-9c07-4b13-8e5a-72f0c4a91e36",
  "timestamp": 1788091200000,
  "data": {
    "id": "3f9c1e77-a4b2-4d10-9e88-6c0f1a7b3d52",
    "operation": "CANTON_CALL",
    "status": "CONFIRMING",
    "subStatus": "PENDING_RECEIVER_APPROVAL",
    "assetId": "CANTON",
    "amount": "0",
    "source": { "type": "EXTERNAL" },
    "destination": { "type": "VAULT_ACCOUNT", "id": "12" },
    "cantonDetails": {
      "offerResponse": {
        "version": 1,
        "domain": "ONBOARDING",
        "vendor": "DTCC",
        "availableResponses": [
          "DTCC_END_INVESTOR_ONBOARDING_ACCEPT",
          "DTCC_END_INVESTOR_ONBOARDING_REJECT"
        ]
      }
    }
  }
}

The same transaction as example 1, after a response was dispatched. availableResponses has emptied and approvalTransactionId names the outgoing response transaction. Posting again here returns 409 response-not-available.This is a genuine state, not a race. The offer is neither answerable nor resolved until the response transaction confirms.

{
  "type": "TRANSACTION_STATUS_UPDATED",
  "tenantId": "d41b6f28-9c07-4b13-8e5a-72f0c4a91e36",
  "timestamp": 1788091260000,
  "data": {
    "id": "3f9c1e77-a4b2-4d10-9e88-6c0f1a7b3d52",
    "operation": "CANTON_CALL",
    "status": "CONFIRMING",
    "subStatus": "APPROVING",
    "assetId": "CANTON",
    "amount": "0",
    "source": { "type": "EXTERNAL" },
    "destination": { "type": "VAULT_ACCOUNT", "id": "12" },
    "cantonDetails": {
      "offerResponse": {
        "version": 1,
        "domain": "ONBOARDING",
        "vendor": "DTCC",
        "availableResponses": [],
        "approvalTransactionId": "5a1d8b0f-2c31-4c7e-9d0a-118e7b6c4a21"
      }
    }
  }
}

The outgoing offer-response transaction created by accepting an allocation, now locked on chain. This data.id is what ALLOCATION_WITHDRAW takes as allocationTransactionId, and this status pair is the only state in which it is accepted.The transaction stays here until the venue settles it, moving to COMPLETED, or a withdraw succeeds, moving it to CANCELLED.

{
  "type": "TRANSACTION_STATUS_UPDATED",
  "tenantId": "d41b6f28-9c07-4b13-8e5a-72f0c4a91e36",
  "timestamp": 1788094800000,
  "data": {
    "id": "9f2b7c14-8d55-4a02-b6e1-5c3f90a7d488",
    "operation": "CANTON_CALL",
    "status": "CONFIRMING",
    "subStatus": "ALLOCATED",
    "assetId": "CANTON",
    "amount": "1000",
    "source": { "type": "VAULT_ACCOUNT", "id": "12" },
    "destination": { "type": "EXTERNAL" },
    "cantonDetails": {
      "offerResponse": {
        "version": 1,
        "domain": "ALLOCATIONS",
        "availableResponses": [],
        "originalTransactionId": "c9e05a37-4b81-4f22-9d68-1a73e8b0c542",
        "verdict": "ACCEPTED"
      }
    }
  }
}

The vault-to-one-time-address transfer case, and the reason the answerability rule exists. One transfer offer flags two transactions with PENDING_RECEIVER_APPROVAL. This is the other one.It matches example 1 on every field you are tempted to filter on, including status, subStatus, and operation. It differs only in availableResponses being empty and originalTransactionId being set. Follow that pointer to find where the answer goes.This transaction is not broken, not a duplicate, and must not be ignored. It is half of the offer’s ledger footprint. It simply is not where the answer goes.

{
  "type": "TRANSACTION_STATUS_UPDATED",
  "tenantId": "d41b6f28-9c07-4b13-8e5a-72f0c4a91e36",
  "timestamp": 1788098400000,
  "data": {
    "id": "b8f30d51-6a27-4c94-8e15-9d03f7a2c168",
    "operation": "CANTON_CALL",
    "status": "CONFIRMING",
    "subStatus": "PENDING_RECEIVER_APPROVAL",
    "assetId": "CANTON",
    "amount": "250",
    "source": { "type": "VAULT_ACCOUNT", "id": "12" },
    "destination": { "type": "ONE_TIME_ADDRESS" },
    "cantonDetails": {
      "offerResponse": {
        "version": 1,
        "domain": "TRANSFER",
        "availableResponses": [],
        "originalTransactionId": "7c4a2f81-3d95-4e60-b1a7-8f24c6d0e913"
      }
    }
  }
}

The venue settled the allocation from example 3, and this is the credit side: a real Canton transaction, already COMPLETED when it is created, carrying the asset and amount you receive.There is nothing to answer and you did not initiate it, so it carries neither offerResponse nor call. Its settlement.originalTransactionId names the allocation it pays for. Without that pointer, this is an unexplained incoming credit.

{
  "type": "TRANSACTION_STATUS_UPDATED",
  "tenantId": "d41b6f28-9c07-4b13-8e5a-72f0c4a91e36",
  "timestamp": 1788102000000,
  "data": {
    "id": "e2704b96-1f83-4d57-a0c9-6b58e3d1f204",
    "operation": "CANTON_CALL",
    "status": "COMPLETED",
    "assetId": "Amulet",
    "amount": "500",
    "source": { "type": "EXTERNAL" },
    "destination": { "type": "VAULT_ACCOUNT", "id": "12" },
    "cantonDetails": {
      "settlement": {
        "version": 1,
        "domain": "ALLOCATIONS",
        "type": "ALLOCATION_SETTLEMENT",
        "originalTransactionId": "9f2b7c14-8d55-4a02-b6e1-5c3f90a7d488"
      }
    }
  }
}

Sub-status reference

Sub-status	New	What it means
`PENDING_RECEIVER_APPROVAL`	No	An offer is outstanding. Not a reliable answerability signal.
`APPROVING`	Yes	A response is in flight on this offer. `availableResponses` is empty while it is, and a second post returns `409`.
`ALLOCATED`	Yes	An allocation is locked on chain and withdrawable. The transaction stays at `CONFIRMING`.
`CONFIRMED`	No	The counterparty accepted.
`REJECTED_BY_RECEIVER`	No	The counterparty rejected.
`RECEIVER_APPROVAL_TIMEOUT`	No	The offer expired unanswered.

Note that CONFIRMING is not transient for Canton. An accepted allocation sits at CONFIRMING with ALLOCATED until the venue settles it.

Delivery semantics

Delivery is at-least-once and unordered. Two notifications for the same transaction can arrive out of timestamp order, and timestamp is not a sequence number. Treat every notification as a state snapshot rather than a transition. There is no previousStatus field, by design. Re-read availableResponses on each notification instead of tracking transitions yourself, and make handling idempotent on data.id plus data.status plus data.subStatus. Parse permissively. Both the envelope and data carry fields beyond this contract, and a strict parser breaks on the next unrelated platform addition.

What your endpoint should return

Status	Effect
`200`	Acknowledged. Fireblocks does not redeliver.
`4XX`	Rejected. Fireblocks redelivers with backoff.
`5XX`	Receiver error. Fireblocks redelivers with backoff.

Acknowledge first and process asynchronously. Holding the connection open while a handler runs risks a timeout, which is indistinguishable from a failure and triggers a redelivery.

Return 5XX for a transient failure, because redelivery is what you want. Do not return 4XX for a payload you will never accept, such as one with no cantonDetails, because that becomes a retry loop. Return 200 and drop it instead.

Reconciling without webhooks

The webhook is the push half of the read side. GET /v1/transactions/{txId} is the pull half, and both carry the identical top-level cantonDetails object. Use the pull path at startup, after downtime, or when a delivery fails. See Read Canton Transactions.

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

Which event fires

Route an incoming notification

The five states to tell apart

Sub-status reference

Delivery semantics

What your endpoint should return

Reconciling without webhooks

​Which event fires

​Route an incoming notification

​The five states to tell apart

​Sub-status reference

​Delivery semantics

​What your endpoint should return

​Reconciling without webhooks

Which event fires

Route an incoming notification

The five states to tell apart

Sub-status reference

Delivery semantics

What your endpoint should return

Reconciling without webhooks