Skip to main content
Webhooks let you receive real-time notifications about your transactions instead of polling the API for updates. As a transaction progresses through its lifecycle, Reeple sends a POST request to your registered webhook URL with the final status.

​
Setting up your webhook URL

Reeple doesn’t currently offer a self-service dashboard for webhook configuration. Contact Reeple to register your webhook URL. Make sure the URL is publicly reachable and doesn’t require authentication to accept the request.

​
Payload shape

FieldData typeDescription
eventStringtransfer.success, transfer.failed, charge.success, or charge.failed
dataObjectThe transaction details: amount, fee, currency, status, reference
data.amountNumberTransaction amount
data.feeNumberTransaction fee
data.currencyStringTransaction currency
data.statusStringsuccess or failed
data.referenceStringTransaction reference — use this to look up the transaction via Get transaction by reference

​
Verifying webhook requests

Only process webhook requests you can verify came from Reeple. Every request includes an x-reeple-signature header — an HMAC-SHA512 hash of the raw request body, signed with your secret key. Recompute the hash yourself and compare it using a constant-time check before trusting the payload. 
const crypto = require('crypto');

const secretKey = process.env.REEPLE_SECRET_KEY;

function signaturesMatch(expected, received) {
  const bufferA = Buffer.from(expected);
  const bufferB = Buffer.from(received);

  if (bufferA.length !== bufferB.length) {
    return false;
  }

  return crypto.timingSafeEqual(bufferA, bufferB);
}

router.post('/webhooks/reeple', (req, res) => {
  const expectedSignature = crypto
    .createHmac('sha512', secretKey)
    .update(JSON.stringify(req.body))
    .digest('hex');

  const receivedSignature = req.headers['x-reeple-signature'];

  if (!signaturesMatch(expectedSignature, receivedSignature)) {
    return res.sendStatus(401);
  }

  // Process the event
  res.sendStatus(200);
});
Reject any request whose signature doesn’t match. A mismatch means the request didn’t come from Reeple.

​
Best practices

  • Use HTTPS — always serve your webhook URL over HTTPS.
  • Respond quickly — return a 2xx status as soon as you’ve accepted the event, and do slower processing (database writes, notifications) asynchronously.
  • Be idempotent — the same event may be delivered more than once. Design your handler so processing it twice is safe.
  • Log events — keep a record of received webhooks for debugging and auditing.
  • Handle retries — a failed or timed-out delivery may be retried, so don’t assume a single delivery attempt.