Webhooks

Afriex sends webhook notifications for key events. The SDK provides a verifier to validate webhook signatures.

Setup

Initialize the SDK with your webhook public key:


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

Verify Webhook Signature


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);
 
    // Handle the event
    switch (event.event) {
      case "CUSTOMER.CREATED":
        console.log("Customer created:", event.data);
        break;
      case "TRANSACTION.CREATED":
        console.log("Transaction created:", event.data);
        break;
      case "PAYMENT_METHOD.CREATED":
        console.log("Payment method created:", event.data);
        break;
    }
 
    res.status(200).send("OK");
  } catch (error) {
    console.error("Invalid signature");
    res.status(400).send("Invalid signature");
  }
});

Event Types

Customer Events

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

Payload:


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

Transaction Events

Event	Description
`TRANSACTION.CREATED`	Transaction was 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: { narration?, invoice?, idempotencyKey?, merchantId? },
    createdAt: string,
    updatedAt: string
  }
}

Payment Method Events

Event	Description
`PAYMENT_METHOD.CREATED`	Payment method was created
`PAYMENT_METHOD.UPDATED`	Payment method was updated
`PAYMENT_METHOD.DELETED`	Payment method was 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? }
  }
}

Signature Verification Only

If you only want to verify the signature without parsing:


const isValid = afriex.webhooks.verify(payload, signature);
 
if (isValid) {
  const event = JSON.parse(payload);
  // Handle event
}