AFafriex
Webhooks

Transaction Events

Afriex sends real-time webhook notifications to your configured URL whenever a transaction is created or updated.

  • TRANSACTION.CREATED: Fired when a new transaction is initiated.
  • TRANSACTION.UPDATED: Fired when the transaction status or other fields change (most commonly status and updatedAt).

The payload structure is identical for both events. Only the event field and potentially status + updatedAt differ.

Security: Every request includes an x-webhook-signature header and an x-afriex-business-id header carrying your business id. You must verify this signature using Afriex's public key before processing. The key is an elliptic-curve (secp384r1 / P-384) key, not RSA. The signature is ECDSA with SHA-256, DER-encoded and then base64-encoded, computed over the exact raw request body, so verify it before parsing or re-serialising the JSON. See the Webhooks Overview & Security section for verification instructions.

postWebhooktransaction.events

Payload

idstring uuid required

Unique ID of this event. Every delivery attempt of the same event carries the same id, so use it to ignore a delivery you have already processed.

event'TRANSACTION.CREATED' | 'TRANSACTION.UPDATED' required

Identifies which transaction event occurred

createdAtstring date-time required

When Afriex created the event. Retries keep this value, and the signature covers it, so you can reject a delivery that is older than you expect.

Example payload

{
  "id": "8f14e45f-ceea-4e7a-9f1d-6b1c2a3d4e5f",
  "event": "TRANSACTION.UPDATED",
  "createdAt": "2026-04-24T09:13:33.883Z",
  "data": {
    "type": "WITHDRAW",
    "channel": "BANK_ACCOUNT",
    "sourceAmount": "3.316587998",
    "sourceCurrency": "USD",
    "destinationAmount": "5000",
    "destinationCurrency": "NGN",
    "sourceId": "695271a3ba52c13b669fad2b",
    "destinationId": "695271a3ba52c13b669fad2b",
    "customerId": "69528240ba52c13b669fb239",
    "transactionId": "6952826eba52c13b669fb263",
    "merchantReference": "order-12345",
    "createdAt": "2025-12-29T13:30:22.554Z",
    "updatedAt": "2025-12-29T13:30:22.554Z"
  }
}

Response

Acknowledge receipt. Return any 2xx status code quickly. Response body is ignored.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.