Ad hoc webhooks

How to secure your callback endpoints

When sending a payment, creating a local withdrawal or ordering a conversion you can provide us a webhook (callback) URI - callbackUri. We will call it when a payment or withdrawal status changes.

We recommend API clients to generate and add ?signature=ASecretPerPaymentKey query to your callbackUri to make sure it's Flash Payments calling your webhook endpoint. For example:

https://my-webhooks.example.com/flash-payments?signature=oZaDlmfXbdXSKCnuWrvos2ImVBFX2Ru5

To avoid storing the signatures in a database we recommend generating them on the fly using a strong hash function or any kind of cryptography.

Example

This is just an example. Feel free to sign your URLs the way you want.

You would need to implement two functions.

1. Function to generate "signature".

2. Function to verify the "signature".

Generating signatures

Node.js pseudo code to generate a signature in your integration code.

const secret = "abcdefg";
function generateSignature(string) {
  return require("node:crypto")
    .createHmac("sha256", secret) // your secret key
    .update(string)
    .digest("base64");
}

const signature = generateSignature(stringIdFromMyDatabase);
const callbackUri = 
  "https://my-webhooks.example.com/flashfx?signature=" + signature;
const externalId = stringIdFromMyDatabase;

// Use both callbackUri and externalId when creating transfers with Flash Payments API

The code above creates a callbackUri and externalId variables. Use both of them when creating a transfer in Flash Payments API.

Verifying signatures

Node.js pseudo code of your webhook HTTP request handler.

function myCallbackEndpointHandler(req, res) {
  const signature = req.query.signature;
  const stringIdFromMyDatabase = req.body.externalId;
  
  if (generateSignature(stringIdFromMyDatabase) !== signature) {
    console.error("Security warning! Webhook endpoint received bad data", req);
    res.sendStatus(500);
    return;
  }
  
  // continue with the webhook processing
}