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.
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.
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_ACCOUNT_ASSET_BALANCE_UPDATED | 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 January 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.