Webhooks - Afriex Business API

The SDK ships helpers for verifying webhook signatures and parsing event payloads. For the full list of webhook events and payload shapes, see the Webhooks reference.

Setup

Pass your webhook public key when initializing the SDK:

const afriex = new AfriexSDK({
  apiKey: process.env.AFRIEX_API_KEY,
  environment: "staging", // or 'production'
  webhookPublicKey: process.env.AFRIEX_WEBHOOK_PUBLIC_KEY,
});

Copy the public key from Developer → Webhook in the dashboard. Sandbox and production have different keys, so use the one that matches environment.

Verify and Parse

The signature covers the exact bytes Afriex sent, so verify the raw request body. If a JSON body parser such as express.json() runs first, you get a parsed object instead of the bytes Afriex signed, and every signature check fails. In Express, read the webhook route with express.raw() and pass the body to the SDK as it is. verify and verifyAndParse take a Buffer or a string: Store each event before you acknowledge it, and act on it afterwards, outside the request. Afriex waits up to 15 seconds for a 2xx, retries anything slower, and sends every event at least once, so key what you store on the event’s id. See Duplicates, ordering, and replays.

import express from "express";
import type { WebhookPayload } from "@afriex/sdk";

const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.headers["x-webhook-signature"] as string;
  const payload: Buffer = req.body; // raw bytes from express.raw(), not parsed JSON

  let event: WebhookPayload;
  try {
    event = afriex.webhooks.verifyAndParse(payload, signature);
  } catch {
    return res.status(400).send("Invalid signature");
  }

  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.status(500).send("Try again"); // not stored, so let Afriex retry
  }

  res.status(200).send("OK");
});

// Run by a worker for each stored event that isn't marked done. Make it safe to
// run twice, and compare data.updatedAt with what you hold, because a retried
// event can arrive after a newer one.
async function processWebhookEvent(event: WebhookPayload) {
  switch (event.event) {
    case "CUSTOMER.CREATED":
    case "CUSTOMER.UPDATED":
    case "CUSTOMER.DELETED":
      console.log("Customer event:", event.data);
      break;
    case "TRANSACTION.CREATED":
    case "TRANSACTION.UPDATED":
      console.log("Transaction event:", event.data);
      break;
    case "PAYMENT_METHOD.CREATED":
    case "PAYMENT_METHOD.UPDATED":
    case "PAYMENT_METHOD.DELETED":
      console.log("Payment method event:", event.data);
      break;
    case "CHECKOUT_SESSION.CREATED":
      console.log("Checkout session event:", event.data);
      break;
    case "POOL_DEPOSIT_REQUEST.REJECTED":
      console.log("Pool deposit rejected:", event.data);
      break;
  }
}

id and createdAt are part of every webhook body. The SDK’s WebhookPayload type includes them from the first release after @afriex/sdk 5.0.0. On 5.0.0, upgrade, or read them from the parsed JSON.

Verify Only

Validate the signature without parsing. payload is the raw body, as above:

const isValid = afriex.webhooks.verify(payload, signature);

if (isValid) {
  const event = JSON.parse(payload.toString("utf8"));
  // Handle event
}

Trigger Test Webhook (Sandbox)

Send a test webhook to your endpoint in sandbox:

const result = await afriex.webhooks.triggerTestWebhook({
  event: "TRANSACTION.UPDATED",
  resourceId: "transaction-id",
});

console.log(result); // { success: true, message: "..." }

For CHECKOUT_SESSION.CREATED, use the checkoutId returned when you created the checkout as resourceId.

Test webhook triggers only work in the sandbox environment.

​Setup

​Verify and Parse

​Verify Only

​Trigger Test Webhook (Sandbox)

Setup

Verify and Parse

Verify Only

Trigger Test Webhook (Sandbox)