Introduction

​

How webhooks work

​

Set up your webhook endpoint

1. Open the Dashboard.
2. Go to Developer.
3. Select the Webhook tab.
4. Save your webhook URL.

• https://your-domain.com/webhook

​

Afriex IP addresses

​

Security and signature validation

• Header: x-webhook-signature
• Algorithm: ECDSA with SHA-256
• Key: elliptic-curve, secp384r1 (P-384). It is not an RSA key.
• Signature format: DER-encoded, then base64-encoded
• Signed data: the exact raw request body (string/Buffer)
• Public key source: Developer → Webhook in the Dashboard
• Environment note: Sandbox and production use different public keys

import crypto from "crypto";

function verifySignature(
  signature: string,
  rawBody: string | Buffer,
  publicKey: string
): boolean {
  try {
    // The key is an EC (P-384) key, so this verifies ECDSA with SHA-256.
    const verifier = crypto.createVerify("SHA256");
    verifier.update(rawBody);
    return verifier.verify(publicKey, signature, "base64");
  } catch {
    return false;
  }
}

​

Response and retries

• On success: return 200 (or another 2xx status). Afriex waits up to 15 seconds for your response before treating the attempt as failed, so aim well inside that budget and do slow work after acknowledging.
• On verification failure: return 400 or 401
• Retry behavior: Afriex makes up to 12 delivery attempts, the first one and then up to 11 retries, with exponential backoff starting at 30 seconds.

• 30s → 1m → 2m → 4m → 8m → 16m → 32m → about 1h → about 2h → about 4h → about 8h

​

Duplicates, ordering, and replays

• The same event more than once. Afriex retries any delivery that doesn’t get a 2xx within 15 seconds, even if you processed it. Store the id of each event you process. When a delivery’s id is one you have, return 200 and skip it.
• Events out of order. A retried event can arrive after a newer one, and TRANSACTION.UPDATED can arrive before TRANSACTION.CREATED. Compare the payload’s data.updatedAt with the version you have stored, and ignore anything older.
• Replayed deliveries. A captured delivery still has a valid signature if someone sends it again. Your stored ids stop a replay, because it carries an id you’ve already processed. Retries can arrive up to about 16 hours after createdAt, so keep each id for at least a day.

// After verifying the signature against the raw body:
const event = JSON.parse(rawBody);

try {
  // A unique key on event.id turns a retry or a replay into a no-op.
  await webhookEvents.insertIfAbsent({ id: event.id, payload: event });
} catch {
  return res.sendStatus(500); // not stored, so let Afriex retry
}

res.sendStatus(200);

// Elsewhere, a worker takes each stored event that isn't marked done, acts on it,
// then marks it done. Make that work safe to run twice, in case the worker
// crashes before it marks the event.

​

Webhook event references

• Customer Events
• Payment Method Events
• Transaction Events
• Checkout Session Events
• Pool Deposit Events