Overview

Push API is an API-based feature which produces notifications, and is designed for programmatic interactions with our systems. For example, if an event occurs in the workspace, like a balance being updated, or a transaction carried out, your API receives a data JSON via a webhook URL that you configure to listen through. 

Configuring API Webhooks

To configure general API webhook notifications in the Fireblocks Console, go to Settings > General > Configure webhook URLs and select Manage URLs.

These API webhooks alert you about additional activities beyond what Notification Center alerts cover, such as system integrations and the triggering of follow-on actions in other applications due to a transaction being created or changing statuses in Fireblocks. Webhooks capture all transaction stages and their corresponding statuses.

If you use API webhooks, an inbound deposit generates the following webhooks when it is detected:

• First, a TRANSACTION_CREATED webhook is triggered with the status SUBMITTED.
• When Fireblocks detects an update to the transaction's number of confirmations on the blockchain, a TRANSACTION_STATUS_UPDATED webhook is triggered, reflecting the updated number of confirmations. The transaction remains in the CONFIRMING status and PENDING_BLOCKCHAIN_CONFIRMATIONS substatus until the required number of confirmations is reached.
• Once the transfer receives enough confirmations, a TRANSACTION_STATUS_UPDATED webhook is triggered with the status COMPLETED and sub-status CONFIRMED.

The id or txHash parameters in the webhook’s data field link these webhooks together.

API webhook examples

Event 1: TRANSACTION_CREATED

"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 2: TRANSACTION_STATUS_UPDATED

  "type": "TRANSACTION_STATUS_UPDATED",
  "tenantId”: ".........-.....-....-....-...........",
  "timestamp": 1679651214621,
  "data": {
      "id": "........-....-....-....-............",
      "createdAt": 1680014718734,
      "lastUpdated": 1680014729691,
      "assetId": "TRX_USDT",
      "source": {
      "id": "",
      "type": "UNKNOWN",
      "name": "External",
       "subType": ""
  },
  "destination": {
      "id": "2107",
      "type": "VAULT_ACCOUNT",
      "name": "Main",
      "subType": ""
  },
  "amount": 370,
  "networkFee": 27.2559,
  "netAmount": 370,
  "sourceAddress": "",
  "destinationAddress": "",
  "destinationAddressDescription": "",
  "destinationTag": "",
  "status": "COMPLETED",
  "txHash": "e9e1asdade125be06638c8675fdsfsdc79594dd45ff095b7683c3f03b81a9389684",
  "subStatus": "CONFIRMED",
  "signedBy": [],
  "createdBy": "",
  "rejectedBy": "",
  "amountUSD": 0,
  "addressType": "",
  "note": "",
  "exchangeTxId": "",
  "requestedAmount": 370,
  "feeCurrency": "TRX",
  "operation": "TRANSFER",
  "customerRefId": "........-....-....-....-............",
  "numOfConfirmations": 1,
  "amountInfo": {
      "amount": "370",
      "requestedAmount": "370",
      "netAmount": "370",
  "amountUSD": null
  },
  "feeInfo": {
      "networkFee": "27.2559"
  },
  "destinations": [],
  "externalTxId": null,
  "blockInfo": {
      "blockHeight": "49800684",
      "blockHash": "0000000002f7e5ece07efd8dfnjngfh76dda5f2645a9aba5e6h4534ba1bc7d97a8e2"
  },
  "signedMessages": [],
  "amlScreeningResult": {
      "screeningStatus": "BYPASSED",
      "bypassReason": "PASSED_BY_POLICY",
      "timestamp": 1680014729455
  },
  "assetType": "TRON_TRC20"
  }
}

If you want to receive notifications about events other than transactions sent to the API webhook server, you should configure both API webhook and Notification Center webhook events:

• See the list of categories and events that trigger Notification Center notifications.
• See the list of general API webhook events in the Developer Portal.

Validating webhook events

You can validate Fireblocks webhook events by validating the signature attached in the request header with a public key. The Fireblocks public keys for mainnet workspaces and developer sandbox workspaces are available to download at the bottom of this article. 

Learn more about configuring and validating webhooks in the developer portal.