Webhooks

Afriex sends webhook notifications for key events. The SDK validates signatures and triggers test events in sandbox.

Setup

Pass your webhook public key during initialization:

const afriex = new AfriexSDK({
  apiKey: "your-api-key",
  webhookPublicKey: "your-afriex-public-key",
});

Verify and Parse

Validate signature and parse payload in one call:

app.post("/webhook", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const payload = req.body; // Raw string body

  try {
    const event = afriex.webhooks.verifyAndParse(payload, signature);

    switch (event.event) {
      case "CUSTOMER.CREATED":
      case "CUSTOMER.UPDATED":
      case "CUSTOMER.DELETED":
        console.log("Customer created:", event.data);
        break;
      case "TRANSACTION.CREATED":
      case "TRANSACTION.UPDATED":
        console.log("Transaction created:", event.data);
        break;
      case "PAYMENT_METHOD.CREATED":
      case "PAYMENT_METHOD.UPDATED":
      case "PAYMENT_METHOD.DELETED":
        console.log("Payment method created:", event.data);
        break;
      case "CHECKOUT_SESSION.CREATED":
        console.log("Checkout session created:", event.data);
        break;
    }

    res.status(200).send("OK");
  } catch (error) {
    console.error("Invalid signature");
    res.status(400).send("Invalid signature");
  }
});

Verify Only

Validate signature without parsing:

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

if (isValid) {
  const event = JSON.parse(payload);
  // 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",
});

// Check your webhook endpoint for the test event
console.log(result); // { success: true, message: "..." }

For CHECKOUT_SESSION.CREATED, use the checkout session UUID as resourceId.

Supported Events:

Event	Resource Type
`CUSTOMER.CREATED`	Customer ID
`CUSTOMER.UPDATED`	Customer ID
`CUSTOMER.DELETED`	Customer ID
`TRANSACTION.CREATED`	Transaction ID
`TRANSACTION.UPDATED`	Transaction ID
`PAYMENT_METHOD.CREATED`	Payment Method ID
`PAYMENT_METHOD.UPDATED`	Payment Method ID
`PAYMENT_METHOD.DELETED`	Payment Method ID
`CHECKOUT_SESSION.CREATED`	Checkout Session UUID

Test webhook triggers only work in sandbox environment.

Event Types

Customer Events

Event	Description
`CUSTOMER.CREATED`	Customer created
`CUSTOMER.UPDATED`	Customer updated
`CUSTOMER.DELETED`	Customer deleted

Payload:

{
  event: 'CUSTOMER.CREATED',
  data: {
    customerId: string,
    name: string,
    email: string,
    phone: string,
    countryCode: string
  }
}

Transaction Events

Event	Description
`TRANSACTION.CREATED`	Transaction created
`TRANSACTION.UPDATED`	Transaction status changed

Payload:

{
  event: 'TRANSACTION.UPDATED',
  data: {
    transactionId: string,
    customerId: string,
    destinationId: string,
    status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | ...,
    type: string,
    sourceAmount: string,
    sourceCurrency: string,
    destinationAmount: string,
    destinationCurrency: string,
    meta: { idempotencyKey, reference, narration?, invoice?, merchantId? },
    createdAt: string,
    updatedAt: string
  }
}

Payment Method Events

Event	Description
`PAYMENT_METHOD.CREATED`	Payment method created
`PAYMENT_METHOD.UPDATED`	Payment method updated
`PAYMENT_METHOD.DELETED`	Payment method deleted

Payload:

{
  event: 'PAYMENT_METHOD.CREATED',
  data: {
    paymentMethodId: string,
    channel: string,
    customerId: string,
    accountName: string,
    accountNumber: string,
    countryCode: string,
    institution: { institutionId?, institutionName?, institutionCode? },
    recipient: { recipientName?, recipientEmail?, recipientPhone? }
  }
}

Checkout Session Events

Event	Description
`CHECKOUT_SESSION.CREATED`	Checkout session created

Payload:

{
  event: 'CHECKOUT_SESSION.CREATED',
  data: Record<string, unknown>
}

On this page