🚧
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 field	New field	Type	Description
-	id	string (UUID)	Unique identifier for the webhook notification object.
type	eventType	enum	Description of the event (e.g., `transaction.created`).
-	resourceId	string (UUID)	(Optional) ID of the entity that triggered the event (e.g., `txid`).
data	data	object	Contains the API resource relevant to the event (e.g., the full transaction object for a `transaction.created` event).
timestamp	createdAt	number	Webhook timestamp.
tenantId	workspaceId	string (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 Category	V1 Event Type	V2 Category	V2 Event Type
Transactions	TRANSACTION_CREATED	Transactions	transaction.created
Transactions	TRANSACTION_STATUS_UPDATED	Transactions	transaction.status.updated
Transactions	TRANSACTIONS_APPROVAL_STATUS_UPDATED	Transactions	transaction.approval_status.updated
Internal, External & Contract Wallet	EXTERNAL_WALLET_ASSET_ADDED	Whitelist	external_wallet.asset.added
Internal, External & Contract Wallet	EXTERNAL_WALLET_ASSET_REMOVED	Whitelist	external_wallet.asset.removed
Internal, External & Contract Wallet	INTERNAL_WALLET_ASSET_ADDED	Whitelist	internal_wallet.asset.added
Internal, External & Contract Wallet	INTERNAL_WALLET_ASSET_REMOVED	Whitelist	internal_wallet.asset.removed
Internal, External & Contract Wallet	CONTRACT_WALLET_ASSET_ADDED	Whitelist	contract_wallet.asset.added
Internal, External & Contract Wallet	CONTRACT_WALLET_ASSET_REMOVED	Whitelist	contract_wallet.asset.removed
Vault	VAULT_ACCOUNT_ADDED	Wallet	vault_account.created
Vault	VAULT_ACCOUNT_ASSET_ADDED	Wallet	vault_account.asset.added
Vault	VAULT_BALANCE_UPDATE	Wallet	vault_account.asset.balance_updated
NFT	VAULT_ACCOUNT_NFT_BALANCE_UPDATED	Wallet	vault_account.nft.balance_updated
Embedded Wallet	NCW_STATUS_UPDATED	Embedded Wallet	embedded_wallet.status.updated
Embedded Wallet	NCW_STATUS_CREATED	Embedded Wallet	embedded_wallet.account.created
Embedded Wallet	NCW_ASSET_CREATED	Embedded Wallet	embedded_wallet.asset.added
Embedded Wallet	NCW_BALANCE_UPDATED	Embedded Wallet	embedded_wallet.asset.balance_updated
Embedded Wallet	NCW_ADD_DEVICE_SETUP_REQUESTED	Embedded Wallet	embedded_wallet.device.added
Exchange & Fiat Account	EXCHANGE_ACCOUNT_ADDED	CeFi	exchange_account.added
Exchange & Fiat Account	FIAT_ACCOUNT_ADDED	CeFi	fiat_account.added
Network Connection	NETWORK_CONNECTION_REMOVED	Network	connection.removed
Network Connection	NETWORK_CONNECTION_ADDED	Network	connection.added
Network Connection	WAITING_FOR_PEER_APPROVAL	Network	connection.request.waiting_peer_approval
Network Connection	REJECTED_BY_PEER	Network	connection.request.rejected_by_peer
Smart Transfer	TICKET_CREATED	Smart Transfer	ticket.created
Smart Transfer	TICKET_SUBMITTED	Smart Transfer	ticket.submitted
Smart Transfer	TICKET_EXPIRED	Smart Transfer	ticket.expired
Smart Transfer	TICKET_CANCELED	Smart Transfer	ticket.canceled
Smart Transfer	TICKET_FULFILLED	Smart Transfer	ticket.fulfilled
Smart Transfer	TICKET_COUNTERPARTY_ADDED	Smart Transfer	ticket.counterparty.added
Smart Transfer	TICKET_COUNTERPARTY_EXTERNAL_ID_SET	Smart Transfer	ticket.counterparty_external_id.set
Smart Transfer	TICKET_NOTE_ADDED	Smart Transfer	ticket.note.added
Smart Transfer	TICKET_EXPIRES_IN_SET	Smart Transfer	ticket.expires_in.set
Smart Transfer	TICKET_EXPIRES_AT_SET	Smart Transfer	ticket.expires_at.set
Smart Transfer	TICKET_TERM_ADDED	Smart Transfer	ticket.term.added
Smart Transfer	TICKET_TERM_UPDATED	Smart Transfer	ticket.term.updated
Smart Transfer	TICKET_TERM_DELETED	Smart Transfer	ticket.term.deleted
Smart Transfer	TICKET_TERM_FUNDED	Smart Transfer	ticket.term.funded
Smart Transfer	TICKET_TERM_MANUALLY_FUNDED	Smart Transfer	ticket.term.manually_funded
Smart Transfer	TICKET_TERM_FUNDING_CANCELED	Smart Transfer	ticket.term.funding_canceled
Smart Transfer	TICKET_TERM_FUNDING_FAILED	Smart Transfer	ticket.term.funding_failed
Smart Transfer	TICKET_TERM_FUNDING_COMPLETED	Smart Transfer	ticket.term.funding_completed
Smart Transfer	TICKET_TERM_TRANSACTION_STATUS_CHANGED	Smart Transfer	ticket.term.transaction_status_changed
Off Exchange	SETTLEMENT_CREATED	Off Exchange	settlement.created
Off Exchange	COLLATERAL_SIGNER_READY_EVENT	Off Exchange	collateral.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.