Console
Docs/Core concepts

Webhooks

Signed events, verified over the raw body, retried until you answer.

#The event

Register one HTTPS URL when the app is onboarded. PayGate POSTs JSON:

JSON
{
  "id": "evt_...",
  "type": "payment.succeeded",
  "occurred_at": "2026-11-02T12:00:00.000Z",
  "data": { "payment_id": "pay_...", "reference": "order-9f2c", "amount": 250000, "currency": "KES" }
}

#Headers

Text
x-paygate-signature: t=1793641837,v1=<hex hmac>
x-paygate-event-id: evt_...

#Verifying the signature

Verify before parsing:

  1. Split t and v1.
  2. Reject if abs(now - t) > 300 seconds.
  3. Compute HMAC-SHA256(secret, t + "." + rawBody) and compare in constant time.
  4. Deduplicate on x-paygate-event-id.

Verify the raw body, never a re-serialised object: whitespace and key order change the digest.

#Retries

Respond 2xx quickly. Any other status is retried with backoff: 10s, 60s, 5m, 30m, 1h, 6h, 12h, 24h, then the event is marked dead and waits for a human in the console. Delivery is at least once, so make your handler idempotent.

#Event types

Event types: payment.succeeded, payment.failed, settlement.approved, settlement.failed, settlement.settled.

Reference

Every route, parameter and response is generated from the OpenAPI 3.1 document.

Open the API reference