Real-time event delivery to your endpoint with signatures, retries, secret rotation, alerts, and replay. Designed for production from day one.
Every POST carries X-Nowpesa-Signature with t=<unix>,v1=<hex_hmac>. Verify server-side with HMAC-SHA256 over `<t>.<body>`.
We retry failed deliveries up to 6 times over ~12 hours. Each attempt is logged in the dashboard with its status code and response snippet.
Rotate your signing secret → both X-Nowpesa-Signature and X-Nowpesa-Signature-Next ship until you Promote. No dropped events.
After N permanent failures we POST a failure-burst alert to your ops URL. We also POST a recovery alert when the endpoint starts succeeding again.
Any past delivery (delivered or failed) can be re-fired with one click. Same event_id, so your idempotency stays intact.
Webhook delivery happens at-least-once via an outbox relay. Your handler should be idempotent on (event_id) — never double-process the same event.
Pass callback_url on any payment or payout to route that request's events to a single URL — skipping your registered endpoints for just that request. Signed with your callback secret, same HMAC scheme.
| Event type | What it means |
|---|---|
| payment.succeeded | Inbound payment captured. Ledger credited. |
| payment.failed | Inbound payment declined or expired. |
| payment.refunded | Refund slice succeeded. Ledger reversed. |
| payment.refund_failed | Refund slice failed at the channel. |
| payout.succeeded | Outbound transfer to M-Pesa completed. |
| payout.failed | Outbound transfer reversed; reservation released. |
Full payload reference at /docs/webhook-events.
