Skip to main content

Documentation Index

Fetch the complete documentation index at: https://fireblocks-43c4b3ee-chore-add-cli.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Deprecation notice Webhooks v1 will be deprecated on June 15th, 2026. Please use the Developer Center in the Fireblocks Console to upgrade to Webhooks V2, which offers improved reliability, performance, and observability.

​
Overview

The new Webhooks V2 service provides a more robust, reliable, faster, and feature-rich integration experience. While the new system introduces many enhanced capabilities, it also deprecates some existing features to streamline functionality and improve performance.

​
Key benefits

  • Improved performance: Reduced response times and increased resiliency.
  • Events catalog: Subscribe to specific events or event categories.
  • Visibility: New UI for notifications and send attempts.
  • Enhanced controls: UI and API management, including notifications, resend up to 30 days.
  • No holdups: Removed existing 10s inherent delay used in V1 to best-effort order messages.
Before you begin
  • This page is not intended to serve as an implementation guide. It only highlights the differences between the Webhooks v1 and Webhooks v2 services and provides an event mapping table.
  • Ensure that you review all Webhooks v2 documentation and implement the service according to your organization’s best practices.
  • If your organization requires IP addresses to be allowlisted, please note that the IP addresses required for Webhooks v2 are different from those of Webhooks v1. Learn more here.

​
Changelog

​
Events

  • Event catalog & subscriptions: Browse the event catalog and subscribe only to the categories or specific event types relevant to your use case. This lets you focus on the events you need, reduce unnecessary processing, and maintain a cleaner integration.
  • Event types: We introduced a new syntax for event types. Use the table below to map your Webhooks v1 events to the new Webhooks v2 syntax.
  • Event ordering: While we attempt to send notifications in order (per resource), Fireblocks doesn’t guarantee delivery of events in the order in which they’re generated. Your endpoint shouldn’t expect the delivery of events in order.

​
Resend capability

We now allow resending events for up to 30 days from the original event timestamp. To initiate a resend, use the resourceId field of the event’s data object. Please note that you can only resend events once every five minutes.

​
Improved retry logic

Retry attempts for failed webhook deliveries now span a longer time window to help ensure delivery success.

​
Error rate monitoring & disabling

Webhooks with an error rate exceeding a specific threshold will be automatically disabled to protect the system integrity. You should handle events asynchronously with queues and quickly return a 2xx status code to prevent performance issues in your application

​
Notifications object differentiation

The new webhook payload format is designed for clarity and extensibility. Below is the structure of the new payload:
Old fieldNew fieldTypeDescription
-idstring (UUID)Unique identifier for the webhook notification object.
typeeventTypeenumDescription of the event (e.g., transaction.created).
-resourceIdstring (UUID)(Optional) ID of the entity that triggered the event (e.g., txid).
datadataobjectContains the API resource relevant to the event (e.g., the full transaction object for a transaction.created event).
timestampcreatedAtnumberWebhook timestamp.
tenantIdworkspaceIdstring (UUID)The tenant or workspace identifier associated with the event.
Notification object has been updated Although the event payload remains unchanged, the notification object has been updated, requiring some adjustments on your end for parsing. Additionally, you’ll need to register your webhook listener on Push API V2 to start using it.

​
Key changes

  • id: Unique identifier for the webhook notification object.
  • type → eventType: Unified event naming for consistency.
  • resourceId: Introduced to enable precise identification of the entity associated with the event.
  • tenantId → workspaceId: The tenant/workspace identifier associated with the event.
  • timestamp → createdAt: Describes when the webhook was created.

​
Event mapping from v1 to v2

Use the table below to help you map your Webhooks v1 events to your Webhooks v2 events.
V1 CategoryV1 Event TypeV2 CategoryV2 Event Type
TransactionsTRANSACTION\_CREATEDTransactionstransaction.created
TransactionsTRANSACTION\_STATUS\_UPDATEDTransactionstransaction.status.updated
TransactionsTRANSACTIONS\_APPROVAL\_STATUS\_UPDATEDTransactionstransaction.approval\_status.updated
Internal, External & Contract WalletEXTERNAL\_WALLET\_ASSET\_ADDEDWhitelistexternal\_wallet.asset.added
Internal, External & Contract WalletEXTERNAL\_WALLET\_ASSET\_REMOVEDWhitelistexternal\_wallet.asset.removed
Internal, External & Contract WalletINTERNAL\_WALLET\_ASSET\_ADDEDWhitelistinternal\_wallet.asset.added
Internal, External & Contract WalletINTERNAL\_WALLET\_ASSET\_REMOVEDWhitelistinternal\_wallet.asset.removed
Internal, External & Contract WalletCONTRACT\_WALLET\_ASSET\_ADDEDWhitelistcontract\_wallet.asset.added
Internal, External & Contract WalletCONTRACT\_WALLET\_ASSET\_REMOVEDWhitelistcontract\_wallet.asset.removed
VaultVAULT\_ACCOUNT\_ADDEDWalletvault\_account.created
VaultVAULT\_ACCOUNT\_ASSET\_ADDEDWalletvault\_account.asset.added
VaultVAULT\_BALANCE\_UPDATEWalletvault\_account.asset.balance\_updated
NFTVAULT\_ACCOUNT\_NFT\_BALANCE\_UPDATEDWalletvault\_account.nft.balance\_updated
Embedded WalletNCW\_STATUS\_UPDATEDEmbedded Walletembedded\_wallet.status.updated
Embedded WalletNCW\_STATUS\_CREATEDEmbedded Walletembedded\_wallet.account.created
Embedded WalletNCW\_ASSET\_CREATEDEmbedded Walletembedded\_wallet.asset.added
Embedded WalletNCW\_BALANCE\_UPDATEDEmbedded Walletembedded\_wallet.asset.balance\_updated
Embedded WalletNCW\_ADD\_DEVICE\_SETUP\_REQUESTEDEmbedded Walletembedded\_wallet.device.added
Exchange & Fiat AccountEXCHANGE\_ACCOUNT\_ADDEDCeFiexchange\_account.added
Exchange & Fiat AccountFIAT\_ACCOUNT\_ADDEDCeFifiat\_account.added
Network ConnectionNETWORK\_CONNECTION\_REMOVEDNetworkconnection.removed
Network ConnectionNETWORK\_CONNECTION\_ADDEDNetworkconnection.added
Network ConnectionWAITING\_FOR\_PEER\_APPROVALNetworkconnection.request.waiting\_peer\_approval
Network ConnectionREJECTED\_BY\_PEERNetworkconnection.request.rejected\_by\_peer
Smart TransferTICKET\_CREATEDSmart Transferticket.created
Smart TransferTICKET\_SUBMITTEDSmart Transferticket.submitted
Smart TransferTICKET\_EXPIREDSmart Transferticket.expired
Smart TransferTICKET\_CANCELEDSmart Transferticket.canceled
Smart TransferTICKET\_FULFILLEDSmart Transferticket.fulfilled
Smart TransferTICKET\_COUNTERPARTY\_ADDEDSmart Transferticket.counterparty.added
Smart TransferTICKET\_COUNTERPARTY\_EXTERNAL\_ID\_SETSmart Transferticket.counterparty\_external\_id.set
Smart TransferTICKET\_NOTE\_ADDEDSmart Transferticket.note.added
Smart TransferTICKET\_EXPIRES\_IN\_SETSmart Transferticket.expires\_in.set
Smart TransferTICKET\_EXPIRES\_AT\_SETSmart Transferticket.expires\_at.set
Smart TransferTICKET\_TERM\_ADDEDSmart Transferticket.term.added
Smart TransferTICKET\_TERM\_UPDATEDSmart Transferticket.term.updated
Smart TransferTICKET\_TERM\_DELETEDSmart Transferticket.term.deleted
Smart TransferTICKET\_TERM\_FUNDEDSmart Transferticket.term.funded
Smart TransferTICKET\_TERM\_MANUALLY\_FUNDEDSmart Transferticket.term.manually\_funded
Smart TransferTICKET\_TERM\_FUNDING\_CANCELEDSmart Transferticket.term.funding\_canceled
Smart TransferTICKET\_TERM\_FUNDING\_FAILEDSmart Transferticket.term.funding\_failed
Smart TransferTICKET\_TERM\_FUNDING\_COMPLETEDSmart Transferticket.term.funding\_completed
Smart TransferTICKET\_TERM\_TRANSACTION\_STATUS\_CHANGEDSmart Transferticket.term.transaction\_status\_changed
Off ExchangeSETTLEMENT\_CREATEDOff Exchangesettlement.created
Off ExchangeCOLLATERAL\_SIGNER\_READY\_EVENTOff Exchangecollateral.status.updated

​
FAQ

​
Is it easy to revert to our original implementation if something goes wrong?

The implementation of the new webhooks is not a migration but a completely new service that runs alongside the original version (V1). You can maintain both integrations in parallel until you’re confident in the new setup. This ensures a smooth transition without needing to revert.

​
How long can I run both services simultaneously?

Both services will run in parallel until the Webhooks v1 service is officially sunset by June 15th, 2026.

​
Are there changes to the payload or our business logic?

The payload and your business logic remain the same. However, the notification object has changed, and you will need to register your webhook server on Push API V2 to start using it.

​
Are new events backwards-compatible with Webhooks v1?

No, and moving forward, new events that we develop will only be supported by the Webhooks v2 service.

​
Where can I get help during the migration process?

Fireblocks Support is always available to assist you with any questions or concerns. If you need assistance, please submit a request.

​
What happens if I don’t migrate by the end-of-life (EOL) date?

We recommend you migrate to the Webhooks v2 service before then. After the EOL date, we will no longer support or provide access to the Webhooks v1 service.