Webhooks

Learn how to listen to events whenever certain actions occur on your integration.

Suggest Edits

What are webhooks?

We trigger events that your application can listen to whenever certain actions occur on your Bitpowr integration. Here's where webhooks come in handy. We deliver payloads for such events to a webhook URL on your server. If you use webhooks, for example, we'll send a transaction.success event to your server as soon as a balance is retrieved. The following is a list of events we can send to your webhook URL.

📘

Helpful Tip

We advise using a webhook instead of a callback to deliver value to your clients. Callbacks can fail if a customer's device's network connection fails or is weak, or if the device turns off after a request, among other things that are beyond our and your control.

You can specify your webhook URL from the Webhook Page on your dashboard where we would send POST requests whenever an event occurs.

Here are some things to note when setting up a webhook URL:

  1. If using .htaccess, remember to add the trailing / to the URL you set.
  2. Do a test post to your URL and ensure the script gets the post body.
  3. Ensure your webhook URL is publicly available (localhost URLs cannot receive events)

Setup webhooks

To set up a new webhook:

  1. From the Environment Switcher in your Bitpowr dashboard, select the environment you want to create a new webhook in.
  2. Select the Developer tab and click webhooks.
  3. Enter the required information in the webhook form.
  • Webhook URL: the URL to receive the webhook notifications.
  • Webhook Secret : an optional secret key to pass along to the request header in order to make your webhook endpoint protected.
    Click Save Changes.

✳️ Done! The webhook is now set up and your application will be notified of new events related to any product opted for.

Receiving an event

All you have to do to receive the event is to create an unauthenticated POST route on your application.
The event object is sent as JSON in the request body.

// Using Express
app.post("/your/webhook/url", function(req, res) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event
    res.send(200);
});

A 200 OK should be used to respond to an event. This is considered an acknowledgment of your application. If your application returns a status other than 2xx, we will consider it unacknowledged and will continue to send it every hour for the next 72 hours. You don't need to provide a request body or any other parameters because they will be ignored - we only care about the status code.

Bitpowr may timeout waiting for a response if your application is likely to start a long-running task in response to the event, in which case the event will be considered unacknowledged and queued to be raised later. You can avoid duplication by having your application respond with a 200 right away before continuing with the rest of the task.

Example incoming webhook

If you're using callbacks with any product, you'll receive a callback when Bitpowr finishes processing the product's data for the Record. Once you receive this callback, you can make an API call to retrieve the product's data.

Below you will see an example of an incoming webhook from Bitpowr's servers. The below example is for AUTH but you will receive webhooks for all products.

Webhook response

If you've set up webhook notifications for your account, we will also send you a response in the format below:

{
  "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"
  }
}

Updated 4 months ago