V4 notifies your backend of money events with signed webhooks. Unlike V3 — which keyed the HMAC on your consumer key — V4 uses a dedicated webhook secret (dashboard → Settings → API Keys → Webhook Secret), so a leaked webhook secret can never be used to forge API requests.

Delivery

• Events are written to an outbox in the same database transaction as the ledger entry — a delivered webhook always corresponds to posted money.
• Delivery is at-least-once with retries; make your handler idempotent on event_id.
• Respond 2xx quickly; do your processing async.

Signature header

PokeaPay-Signature: v4=<hex HMAC-SHA256>

The HMAC is computed over the canonical form (version v4.webhook, key-sorted, length-prefixed) of the event fields — which include event_id and ts, binding each delivery against replay.

Event example

{
  "event_id": "evt_01J…",
  "ts": 1774000000,
  "type": "payout.completed",
  "reference": "PAY-2026-0107",
  "amount_minor": 500000,
  "currency": "KES",
  "rail_reference": "AG_2026…"
}

Event types include collection.completed, collection.failed, payout.completed, payout.failed. Always verify the signature before trusting a payload — see Verifying Signatures.