​

Webhooks

​

Delivery Signing & Secret Management

• Secret Creation & Rotation: When creating a webhook endpoint, a signing secret can be set or automatically generated (secret: "whsec_..."). Platform-issued secrets are returned only once at creation time. Calling POST /organizations/{id}/webhooks/{endpointId}/rotate-secret invalidates the previous secret immediately and returns a new replacement secret.
• Signature Verification: When a signing secret is active, outbound deliveries include the following HTTP headers:
  • X-Webhook-Signature: Format sha256=<hex_digest> (or v1=<hex_digest>).
  • X-Webhook-Timestamp: Unix timestamp (in seconds) of the delivery attempt.
• HMAC Calculation: The signature is computed using HMAC-SHA256 over the exact raw request payload string ({timestamp}.{rawBody} or exact JSON string). Do not parse and re-serialize JSON prior to verification.

​

Node.js Signature Verification Example

import crypto from "node:crypto";

export function verifyWebhook({ rawBody, headers, secret }) {
  const timestamp = headers["x-webhook-timestamp"];
  const signatureHeader = headers["x-webhook-signature"];

  if (!timestamp || !signatureHeader) return false;

  // Reject stale requests older than 5 minutes to prevent replay attacks
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) return false;

  const hash = signatureHeader.replace(/^sha256=|^v1=/, "");
  const expectedHash = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expectedHash));
}

​

Event Envelope & Payload Schemas

{
  "id": "evt_9876543210",
  "type": "payment.settled",
  "createdAt": "2026-07-25T08:30:00.000Z",
  "data": {
    "id": "c1f7b8a2-3e4d-4f1a-b2c3-5d6e7f8a9b0c",
    "reference": "ORD-2026-0042",
    "sourceAmount": 100.00,
    "sourceCurrency": "EUR",
    "targetAmount": 160000.00,
    "targetCurrency": "NGN",
    "exchangeRate": 1600.00,
    "status": "settled",
    "previousStatus": "executed"
  }
}

​

Payment Data Fields

• id: Unique Payment ID (uuid)
• reference: Your unique payment reference
• sourceAmount: Source currency amount
• sourceCurrency: Source ISO 4217 currency code
• targetAmount: Target currency amount
• targetCurrency: Target ISO 4217 currency code
• exchangeRate: Currency conversion exchange rate
• status: Current status (created, initiated, executed, settled, failed, cancelled)
• previousStatus (optional): Prior payment status before this state transition

​

Payment Lifecycle: payment.executed vs payment.settled

[!IMPORTANT] payment.succeeded is not an implemented outbound event name. The actual success events emitted by the platform are payment.executed and payment.settled.

• payment.executed: The upstream provider confirmed that funds were received. Funds are credited to your organization’s pending balance.
• payment.settled: Funds have completed settlement processing and are available in your wallet balance.

​

Outbound Event Catalog

[!NOTE] Outbound events use explicit event types like transfer.completed. Generic transaction.created or transaction.completed events are not emitted because internal ledger Transaction objects cover multiple movement types (fees, refunds, withdrawals).

​

Retry Policy & Deduplication

​

Exponential Backoff Retry Schedule

• 1 hour after first failure
• 2 hours after second failure
• 4 hours after third failure
• 8 hours after fourth failure
• 16 hours after fifth failure
• Deliveries cease after 5 retries (as the next backoff interval would exceed 24 hours).

​

Replay & Deduplication Protection

​

Testing & Manual Resends

• Manual Resend: Webhook delivery logs maintain execution history. You can manually resend failed or historical events using POST /organizations/{id}/webhooks/{endpointId}/deliveries/{deliveryId}/resend.
• Signature Verification Testing: You can test signature verification using stored test credentials or synthetic payload verification in your integration test suite.