Webhooks v1

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:

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

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