Webhooks

A webhook sends a POST request with a charge's data to a URL whenever it's created or its status changes.

Creating webhooks

The way you create webhooks is through your Bidali account Dashboard. Simply select the Developers > Webhooks item from the sidebar menu and you will be presented with this user interface:

Webhooks Dashboard

In order to receive these requests, you should create an endpoint in your server to process it.

Webhook form

You'll need to specify the URL the request will be sent to and a secret. An HMAC signature will be sent in the x-bidali-signature header and you'll be able to compute it using the secret.

This allows you to validate that the events were sent by Bidali, not by a third party.

Webhook payload

The webhook's POST request payload is the charge itself. Here's what a successful charge looks like.

If you'd like to learn more about the different status codes check the onChargeUpdated callback section.

{
  "id": "9a4f03cb-1948-4780-81ba-b8a53a7f6468",
  "amount": "5",
  "metadata": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@bidali.com"
  },
  "createdAt": "2018-08-17T18:43:11.808Z",
  "expiresAt": "2018-08-17T18:58:11.733Z",
  "description": null,
  "statusCode": 300,
  "redirectUrl": null,
  "status": "success",
  "currency": "USD",
  "organization": "pk_viqah4squsnuw6p0e1ue",
  "timeline": [
    {
      "id": "4fd18c22-98e3-4200-93a1-8fe85ba0526d",
      "time": "2018-08-17T18:43:11.808Z",
      "type": "CHARGE_CREATED",
      "status": "pending"
    },
    {
      "id": "60aa266c-b5ad-4ca9-ba5b-cd59593c0e46",
      "time": "2018-08-17T18:43:17.884Z",
      "type": "ETHEREUM_TRANSACTION_CREATED",
      "status": "processing"
    },
    {
      "id": "79690a0e-b199-4ff5-bc06-74311aea80e5",
      "time": "2018-08-17T18:43:49.051Z",
      "type": "ETHEREUM_TRANSACTION_CONFIRMED",
      "status": "processing"
    },
    {
      "id": "d3937d73-def9-4015-acaf-8f109c87a67d",
      "time": "2018-08-17T18:44:35.822Z",
      "type": "ETHEREUM_TRANSACTION_CONFIRMED",
      "status": "processing"
    },
    {
      "id": "0fbfd113-7237-4468-9d5d-79c07136e2ef",
      "time": "2018-08-17T18:44:54.033Z",
      "type": "ETHEREUM_TRANSACTION_CONFIRMED",
      "status": "success"
    }
  ],
  "payments": {
    "ethereum": {
      "transactions": [
        {
          "hash": "0xdf12ce66a4a2b54b3465c6f5394963cd759dab24142f339e4b675ad7d73dd6fa",
          "amount": "0.01743",
          "confirmations": 3
        }
      ],
      "requiredConfirmations": 3,
      "balance": "0.01743",
      "pending": "0",
      "outstanding": "0"
    }
  },
  "quotes": {
    "ethereum": {
      "rate": "0.003486",
      "amount": "0.01743",
      "address": "0x9617fa5ff408dfc0115e0ae1532fa9e75428de61",
      "currency": "ETH"
    }
  }
}

Listening to Webhook events

Creating a Webhook endpoint on your server is really no different from creating any other page on your website. Of course things will be different depending on which language or framework you're building your application with. Here are a few examples:

Ruby
Python
PHP
JavaScript
require 'json'

# Using Sinatra
post '/my/webhook/url' do
  # Retrieve the request's body and parse it as JSON:
  webhookEvent = JSON.parse(request.body.read)

  # Write some logic to handle the `webhookEvent`
  status 200
end
import json
from django.http import HttpResponse

# Using Django
def my_webhook_view(request):
  # Retrieve the request's body and parse it as JSON:
  webhookEvent = json.loads(request.body)

  # Write some logic to handle the `webhookEvent`
  return HttpResponse(status=200)
// Retrieve the request's body and parse it as JSON:
$input = @file_get_contents('php://input');
$webhookEvent = json_decode($input);

// Write some logic to handle the `$webhookEvent`
http_response_code(200); // PHP 5.4 or greater
// This example uses Express to receive webhooks
const app = require('express')();

// Retrieve the raw body as a buffer and match all content types:
app.use(require('body-parser').raw({ type: '*/*' }));

app.post('/my/webhook/url', (request, response) => {
  // Retrieve the request's body and parse it as JSON:
  const webhookEvent = JSON.parse(request.body);

  // Write some logic to handle the `webhookEvent`
  response.send(200);
});

Responding to an event

In order for us to acknowledge that you have received the POST request, your server should respond with a 200 HTTP status. If your server responds with a 400 or higher HTTP status code we'll retry sending the POST request up to six times every ten minutes.

results matching ""

    No results matching ""