2xx, and keeps every attempt so you can see what happened.
1. Add your endpoint
In the dashboard: Settings → Webhooks → Add endpoint. Enter a publichttps:// URL. You get a signing secret (whsec_…) once: store it next to your API key.
Only the business owner can add, change or remove the endpoint (it decides where payment data goes). API keys can’t. Anyone with
read can see deliveries.2. Handle events
Every request is aPOST with a JSON body:
data.environment is test (Development) or live. Amounts are in cents.
Headers: CloudPay-Event-Id (same as id), CloudPay-Event-Type, and CloudPay-Signature.
3. Verify the signature
CloudPay-Signature: t=1763362000,v1=5c0a… is HMAC-SHA256 of <t>.<raw body> with your secret, in hex. Check it against the raw body before parsing, and reject old timestamps.
4. Answer quickly, process once
- Reply
2xxwithin 10 seconds. Do slow work (fulfilment, emails) after replying. - Events can arrive more than once and out of order. Store
idand skip ones you’ve seen. - Treat the event as a nudge: if you need certainty,
GET /v1/merchants/{id}/collections/{collectionID}and act on what that says.
Retries and the trail
Anything other than2xx (or no answer) is retried after 1 min, 5 min, 30 min, 2 h, 5 h, then every 10 h: 8 attempts, about 38 hours. After that the event is failed.
Settings → Webhooks → Deliveries lists every event. Open one to see each attempt: your server’s status code, the first 1 KB of its answer, how long it took, and the exact payload. Send again re-sends a delivered or failed event. The same is in the API:
Cloudpay’s own IPN addresses
Providers notify Cloudpay too. Settings → Webhooks → Cloudpay IPN addresses (orGET /v1/merchants/{id}/ipn-urls) lists them with copy buttons:
- Paste: Paystack has one webhook URL per account. If you use your own Paystack keys, paste Cloudpay’s Paystack address there. See Paystack.
- Automatic: Daraja and SasaPay get their callback address with every request. Nothing to set.
Security
- Endpoints must be public
https://addresses. Addresses that resolve to private or local networks are refused. - Rotate the secret from the dashboard if it leaks. The old one stops working at once.
- Don’t trust an event that fails the signature check, even if it looks right.