# Afriex Webhooks Documentation

Afriex sends real-time webhook notifications to your configured endpoint when important resource changes happen.

## How webhooks work

Afriex delivers event notifications for customer, payment method, transaction, and checkout session updates to the webhook URL you configure in your dashboard.

## Set up your webhook endpoint

1. Open the **Dashboard**.
2. Go to **Developers**.
3. Select the **Webhooks** tab.
4. Save your webhook URL.

Example webhook URLs:

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

After you save your webhook URL, you can copy your webhook public key from the same screen.

## Afriex IP addresses

**Allowlist these IPs before going live.** To receive webhook deliveries, your server must allow inbound traffic from the following Afriex IP addresses:

| Environment | IP Address |
| --- | --- |
| Sandbox | `34.234.189.210` |
| Production | `34.197.33.100` |

Add these to your firewall allowlist. Without this, Afriex webhook requests will be blocked.

## Security and signature validation

Every webhook request includes an `x-webhook-signature` header. You must validate this signature before processing the payload.

- Header: `x-webhook-signature`
- Signature type: Base64-encoded `RSA-SHA256`
- Signed data: Raw request body (`string`/`Buffer`)
- Public key source: **Dashboard -> Developers -> Webhooks**
- Environment note: Staging and production use different public keys

Always verify against the raw request body bytes. Do not verify parsed JSON.

```javascript
import crypto from "crypto";

function verifySignature(
  signature: string,
  rawBody: string | Buffer,
  publicKey: string
): boolean {
  try {
    const verifier = crypto.createVerify("RSA-SHA256");
    verifier.update(rawBody);
    return verifier.verify(publicKey, signature, "base64");
  } catch {
    return false;
  }
}
```

## Response and retries

Return a success response quickly after verification and processing.

- On success: return `200` (or another `2xx` status) within about 5 seconds
- On verification failure: return `400` or `401`
- Retry behavior: Afriex retries failed deliveries up to 12 times with exponential backoff (starting at 30 seconds).

The intended retry schedule is:

- 30s → 1m → 2m → 4m → 8m → 16m → 32m → 1h → 2h → 4h → 8h → 16h

## Webhook event references

- [Customer Events](https://docs.afriex.com/api-reference/endpoint/webhooks/customer-events)
- [Payment Method Events](https://docs.afriex.com/api-reference/endpoint/webhooks/payment-method-events)
- [Transaction Events](https://docs.afriex.com/api-reference/endpoint/webhooks/transaction-events)
- [Checkout Session Events](https://docs.afriex.com/api-reference/endpoint/webhooks/checkout-session-events)