Webhooks are publicly accessible URLs so that anyone can send requests to them. To ensure that the requests are coming from Bitpowr, we include a x-webhook-secret header in the request.

How to Verify Webhook Requests:

  1. Set Up Webhook Secret: When setting up a webhook, specify a secret. This secret is used to verify that the request is coming from Bitpowr. We recommend using a random value. It would be best to store the secret as an environment variable on your server.

  2. Inspect Request Header: We include the webhook secret in the request header labeledx-webhook-secret when sending a webhook request.

  3. Verification Process: When you receive a webhook request, check the value of the x-webhook-secret header (in Base64 encoding) and compare it with the webhook secret you set. If the values match, the request is verified, and If the values do not match, then the request is not from Bitpowr.

๐Ÿ“˜

Webhook secret in Base64 encoding.

The Webhook secret attached to the header is in Base64 encoding. It would be best if you decoded that before comparing.

If you find a request not from Bitpowr, you should discard the request. Please don't process the request or take any action based on the request.

Here are some tips for setting up a webhook secret:

  1. Use a random value for the secret.
  2. Store the secret as an environment variable on your server.
  3. Check the x-webhook-secret header on all incoming webhook requests.
  4. Discard requests that do not have the x-webhook-secret header or have a secret that does not match your set secret.

By following these tips, you can help to protect your webhooks from unauthorized access.

Webhook Payload Structure

Every webhook payloads request made by Bitpowr follow the below basic structure:

  1. event: describing the event
  2. data: An object containing the data associated with the event. The data might varies base on the type of event.

Webhook Payload Example

Here are some examples of webhook payloads for transactions:

{
  "event": "transaction.incoming",
  "data": {
    "status": "SUCCESS",
    "confirmation": 1,
    "type": "DEPOSIT",
    "address": "0x940e2eda985aefa2ac2879e6ef2c20d709444c12",
    "senderAddress": "0xf845f557b16f2399b9807129f40773f5c804fcf8",
    "hash": "0x7ff0d6c55d208a1ea5c538d92d849e6fc97de064fdf4d0d37ef01e463b054c72",
    "chain": "ETHEREUM",
    "amount": "0.001948983410253212",
    "assetType": "ETH",
    "assetId": "913ea13d-f218-42f0-bc4e-9b102f5960e2",
    "accountId": "fbe283f0-88d7-4a4e-8629-b75abb14c83f",
    "subAccountId": null
  }
}
{
  "event": "transaction.awaiting_confirmation",
  "data": {
    "status": "AWAITING_CONFIRMATION",
    "confirmation": 0,
    "type": "TRANSFER",
    "address": "0x33ac59cb78165ee8c80079469d10041b2430f054",
    "from": [
      {
        "id": "1ac54cb2-aef6-436c-8e79-e7dd4407d44b",
        "chain": "ETHEREUM",
        "value": "0.001701651711734",
        "address": "0x9da3fb1f544eae42d1b3ee87ce11b61757b416fc",
        "asset_id": "868797c7-49d2-4b61-9b67-959b4509d883",
        "currency": "ETH",
        "account_id": "a5bd6a60-06f5-49af-8dc5-c9475c16b3e2"
      }
    ],
    "hash": "0xb336b774fe47ae61d4f4fe1e4189d5884d9a50076e498bfa495368134c9eddb3",
    "chain": "ETHEREUM",
    "amount": "0.00165602",
    "fee": "0.000045631711734",
    "assetType": "ETH",
    "ref": "BTP-Se#GbXFtm$lJsryOHn0MJpit#BSoYk",
    "assetId": "a0e27f7b-83c7-4f39-be3f-80603611db4e",
    "accountId": "4bc7f58e-6d6c-47de-939b-9713605f02b0"
  }
}
{
  "event": "transaction.success",
  "data": {
    "status": "SUCCESS",
    "confirmation": 1,
    "type": "TRANSFER",
    "address": "0x33ac59cb78165ee8c80079469d10041b2430f054",
    "from": [
      {
        "id": "1ac54cb2-aef6-436c-8e79-e7dd4407d44b",
        "chain": "ETHEREUM",
        "value": "0.001701651711734",
        "address": "0x9da3fb1f544eae42d1b3ee87ce11b61757b416fc",
        "asset_id": "868797c7-49d2-4b61-9b67-959b4509d883",
        "currency": "ETH",
        "account_id": "a5bd6a60-06f5-49af-8dc5-c9475c16b3e2"
      }
    ],
    "hash": "0xb336b774fe47ae61d4f4fe1e4189d5884d9a50076e498bfa495368134c9eddb3",
    "chain": "ETHEREUM",
    "amount": "0.00165602",
    "fee": "0.000045631711734",
    "gasLimit": "21000",
    "gasPrice": "2172938654",
    "assetType": "ETH",
    "ref": "BTP-Se#GbXFtm$lJsryOHn0MJpit#BSoYk",
    "assetId": "a0e27f7b-83c7-4f39-be3f-80603611db4e",
    "accountId": "4bc7f58e-6d6c-47de-939b-9713605f02b0"
  }
}
{
  "event": "transaction.failed",
  "data": {
    "status": "FAILED",
    "confirmation": null,
    "type": "TRANSFER",
    "address": "TCxF8YwwR693jcZUzsJE93tnJAUo3BdpGB",
    "from": null,
    "hash": null,
    "chain": "TRON",
    "amount": "881.83421517",
    "fee": "0",
    "assetType": "TRON",
    "ref": "BTP-2bldPPHJlkrzBimKZeBD4tRGduTs43",
    "assetId": "ad69fa10-93c4-4bc7-ba61-6130af8ae568",
    "accountId": "753c595d-0b53-471e-8ab5-ef9f151f9fa5"
  }
}
{
  "event": "transaction.new",
  "data": {
    "status": "PENDING",
    "confirmation": null,
    "type": "TRANSFER",
    "address": "TCxF8YwwR693jcZUzsJE93tnJAUo3BdpGB",
    "from": null,
    "hash": null,
    "chain": "TRON",
    "amount": "881.83421517",
    "fee": "0",
    "assetType": "TRON",
    "ref": "BTP-2bldPPHJlkrzBimKZeBD4tRGduTs43",
    "assetId": "ad69fa10-93c4-4bc7-ba61-6130af8ae568",
    "accountId": "753c595d-0b53-471e-8ab5-ef9f151f9fa5"
  }
}