Webhooks

A webhook is a URL on your server where we send payloads for select events. For example, if you implement webhooks, we will immediately notify your server with a payout.transfer.success event when you make a successful payout

Whenever you receive a webhook notification from us, return a 200 OK to avoid resending the same event again from our server.

Set up

You can set up your webhook URL on the dashboard via the Developers page as shown:

Events

Events sent to your webhook URL have event types that provide more information about the event.

Here are the different event types:

Event Type	Description
`payout.transfer.failed`	The transfer to the beneficiary account failed.
`payout.transfer.success`	The transfer was successfully sent to the beneficiary account.
`beneficiary.status.changed`	When a beneficiary status has been updated.
`virtualcard.transaction.debit`	Debit Transactions on Virtual Cards
`virtualcard.transaction.reversed`	Reversed Transactions on Debited Transactions
`virtualcard.transaction.credit`	Credit Transactions on Virtual Card
`virtualcard.user.kyc.success`	User successfully registered
`virtualcard.user.kyc.failed`	User KYC registration failed.
`virtualcard.created.success`	Virtual card created successfully
`virtualcard.created.failed`	Error creating virtual card
`virtualcard.transaction.declined`	Card transaction was declined by a vendor.

Verifying Events

Verifying that these events come from Brails is necessary to avoid creating transactions due to a fraudulent event.

To verify events, validate the x-brails-signature header sent with the event. The HMAC SHA512 signature is the event payload signed with your secret key.

const crypto = require('crypto');
const webhookSecret = process.env.BRAILS_WEBHOOK_SECRET;
// Using Express
app.post("/webhook_url", function(req, res) {
  //validate event
  const hash = crypto.createHmac('sha512', webhookSecret).update(JSON.stringify(req.body)).digest('hex');
  if (hash == req.headers['x-brails-signature']) {
  // Retrieve the request's body
  const event = req.body;
  // Do something with event  
  }
  res.send(200);
});

Notification Retries

When posting notifications, we expect to receive a 200 response code from you. If the response code is not 200, we retry sending the event 3 times after the first failure.

This way, whenever you experience downtime on your end, your updates will still be sent.

Don't rely on webhooks entirely

🚧

We recommend that you set up a service to always query transactions, in the event that webhooks keep failing.

Testing Webhooks

Since notifications must always be available on a publicly accessible URL, you are likely to run into issues while starting to build your application in a local environment. You can easily get around this by using a tool like ngrok (opens in a new tab) or localtunnel (opens in a new tab)

Create a tunnel, and update the new webhook URL setting on your dashboard. Only do this in your test environment to avoid leaking data to the public.

Uganda Beneficiary Virtual Accounts Webhook