Overview
Webhooks provide real-time notifications for events happening within your Fireblocks workspace, such as incoming and outgoing transactions, transaction status updates, and the addition of new vault accounts, contract wallets, internal wallets, or external wallets. By configuring webhooks, you can 'listen' for these events at your chosen URL, ensuring that all relevant event types are broadcast to your designated endpoint.
Using webhooks offers several benefits, particularly for event-driven development. They enable immediate awareness of critical events, allowing your systems to respond quickly and automatically to changes in your workspace. This real-time monitoring enhances operational efficiency, as it can trigger automated workflows, updates, or alerts based on the specific events received. Webhooks also facilitate seamless integration with your existing applications, enabling more dynamic and responsive interactions between your Fireblocks workspace and other platforms.
When implementing webhooks, consider the reliability and scalability of the receiving endpoint. Ensure that your system can handle the volume of incoming events and process them efficiently.
If notifications are missed due to any issue, Fireblocks offers the following API endpoints for resending webhook notifications:
- Resend failed webhooks - Resends all failed webhook notifications
- Resend webhooks for a transaction by ID - Resends webhook notifications for a transaction by its unique identifier
Key Features:
- Event Ordering - Webhook events are sent in order with a 10-second delay.
- Retry Logic - Missed Webhooks are retried every 5, 15, 35, 75, 155, 315, 635, 1275, 2555 (in seconds).
Payload Structure
We have a standard payload structure that we implement throughout, as shown below:
Parameter | Type | Description |
---|---|---|
type | string | The event type. For example: VAULT_ACCOUNT_ADDED |
tenantId | string | Unique ID of your Fireblocks workspace |
timestamp | number | Timestamp in milliseconds |
data | object | Object details |
Below is a sample of the payload response:
{
"type": "TRANSACTION_CREATED",
"tenantId”: ".........-.....-....-....-...........",
"timestamp": 1679651214621,
"data": {
"id": "........-....-....-....-............",
"createdAt": 1679651104380,
"lastUpdated": 1679651104380,
"assetId": "WETH_TEST3",
"source": {
"id": "0",
"type": "VAULT_ACCOUNT",
"name": "Main",
"subType": ""
},
"destination": {
"id": "12",
"type": "VAULT_ACCOUNT",
"name": "MintBurn",
"subType": ""
},
"amount": 0.001,
"sourceAddress": "",
"destinationAddress": "",
"destinationAddressDescription": "",
"destinationTag": "",
"status": "SUBMITTED",
"txHash": "",
"subStatus": "",
"signedBy": [],
"createdBy": ".........-.....-....-....-...........",
"rejectedBy": "",
"amountUSD": null,
"addressType": "",
"note": "",
"exchangeTxId": "",
"requestedAmount": 0.001,
"feeCurrency": "ETH_TEST3",
"operation": "TRANSFER",
"customerRefId": null,
"amountInfo": {
"amount": "0.001",
"requestedAmount": "0.001"
},
"feeInfo": {},
"destinations": [],
"externalTxId": null,
"blockInfo": {},
"signedMessages": [],
"assetType": "ERC20"
}
}
Event Types
Category | Event Type |
---|---|
Transactions | TRANSACTION_CREATED |
Transactions | TRANSACTION_STATUS_UPDATED |
Transactions | TRANSACTION_APPROVAL_STATUS_UPDATED |
Internal, External & Contract Wallet | EXTERNAL_WALLET_ASSET_ADDED |
Internal, External & Contract Wallet | EXTERNAL_WALLET_ASSET_REMOVED |
Internal, External & Contract Wallet | INTERNAL_WALLET_ASSET_ADDED |
Internal, External & Contract Wallet | INTERNAL_WALLET_ASSET_REMOVED |
Internal, External & Contract Wallet | CONTRACT_WALLET_ASSET_ADDED |
Internal, External & Contract Wallet | CONTRACT_WALLET_ASSET_REMOVED |
Vault | VAULT_ACCOUNT_ADDED |
Vault | VAULT_ACCOUNT_ASSET_ADDED |
Vault | VAULT_BALANCE_UPDATE |
NFT | NFT_BALANCE_CHANGED |
Exchange & Fiat Account | EXCHANGE_ACCOUNT_ADDED |
Exchange & Fiat Account | FIAT_ACCOUNT_ADDED |
Network Connection | NETWORK_CONNECTION_ADDED |
Smart Transfer | TICKET_CREATED |
Smart Transfer | TICKET_SUBMITTED |
Smart Transfer | TICKET_EXPIRED |
Smart Transfer | TICKET_CANCELED |
Smart Transfer | TICKET_FULFILLED |
Smart Transfer | TICKET_COUNTERPARTY_ADDED |
Smart Transfer | TICKET_COUNERPARTY_EXTERNAL_ID_SET |
Smart Transfer | TICKET_NOTE_ADDED |
Smart Transfer | TICKET_EXPIRES_IN_SET |
Smart Transfer | TICKET_EXPIRES_AT_SET |
Smart Transfer | TICKET_TERM_ADDED |
Smart Transfer | TICKET_TERM_UPDATED |
Smart Transfer | TICKET_TERM_DELETED |
Smart Transfer | TICKET_TERM_FUNDED |
Smart Transfer | TICKET_TERM_MANUALLY_FUNDED |
Smart Transfer | TICKET_TERM_FUNDING_CANCELED |
Smart Transfer | TICKET_TERM_FUNDING_COMPLETED |
Smart Transfer | TICKET_TERM_TRANSACTION_STATUS_CHANGED |
Off Exchange | SETTLEMENT_CREATED |
Off Exchange | COLLATERAL_SIGNER_READY_EVENT |
IP Whitelisting
Whitelisting Webhook IP addresses is optional but recommended. Webhooks are sent from the following IPs:
- US environment:
3.134.25.131
3.23.47.185
18.223.19.147
3.141.88.232
18.189.135.42
3.139.180.201
18.218.24.251
3.139.250.63
18.116.167.158
3.16.243.177 - EU environment:
3.72.125.45
18.184.217.45
18.198.71.192