Transfer Webhooks

In this guide, we’ll explore how to register and consume transfer webhooks to seamlessly integrate your app with Supesa. With these webhooks, your app can be notified in real-time about fund transfers, deposits, or withdrawals made via Supesa.

Registering Transfer Webhooks

To register a new webhook, you need to have a URL in your app that Supesa can call. You can set up a new transfer webhook from the Supesa dashboard under API settings. Name your webhook, select the transfer events you're interested in, and provide your URL.

Once set, Supesa will ping your application with a webhook each time a relevant transfer event occurs. In the following section, we delve into how to effectively consume these webhooks.

Consuming Transfer Webhooks

Upon receiving a webhook request from Supesa, inspect the type attribute to identify the triggering event. The prefix of the event type will inform you about the nature of the transfer, e.g., deposit, withdrawal, etc.

{
  "id": "a056V7R7NmNRjl70",
  "type": "deposit.completed",
  "payload": {
    "id": "WAz8eIbvDR60rouK",
    "amount": 100.00,
    "currency": "NGN",
    "user_id": "bfcfd1fa-8a74-4727-87ce-fbeee2b536ab"
  }
}

In the example above, a deposit status was updated, and the payload type is a deposit.

Transfer Event Types

{
  "id": "b123K8L9OpQRst45",
  "type": "withdrawal.completed",
  "payload": {
    "id": "YTuDFGHdIJKNLm8z",
    "amount": 150.00,
    "currency": "NGN",
    "user_id": "bfcfd1fa-8a74-4727-87ce-fbeee2b536ab",
    "account": {
      "id": "WAz8eIbvDR60rouK",
      "account_number": "9876543210",
      "bank_name": "Bank of Supesa"
    },
    "status": "Completed",
    "timestamp": 709104300
  }
}

Security

To know for sure that a webhook was, in fact, sent by Supesa instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named x-supesa-signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

const signature = req.headers['x-supesa-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the x-supesa-signature header, you can be sure that the request was truly coming from Supesa. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Supesa. Don't commit your secret webhook key to GitHub!