Webhooks
Receive real-time notifications when transactions succeed or fail.
Webhooks notify your system when a transaction changes status, so you do not have to poll the API. They are optional but strongly recommended for API integrations.
1. Enabling Webhooks
- Go to Integration → API Integration → Webhooks.
- Enter the HTTPS URL of your endpoint.
- Copy the webhook secret shown after saving. You need it to verify signatures.
- Use the test button to send a test event to your endpoint.
2. Events
PEI sends events for Earn success and failure, Spend completion, cancellation and failure, and Spend reversals. Each event has a stable event_id; use it to ignore duplicates.
3. Verifying Signatures
Every request is signed with HMAC-SHA256 using your webhook secret. Verify the signature header against the raw request body and reject requests whose timestamp is older than five minutes. Code samples in Node.js, Python and Ruby are in the Webhooks documentation.
4. Retries
Respond with a 2xx status within 30 seconds. Failed deliveries are retried with increasing delays for several hours. Deliveries are at-least-once, so the same event may arrive more than once.
5. Rotating the Secret
You can rotate the secret in the dashboard. For 24 hours both the old and the new secret are used to sign events, so you can switch without downtime.
6. If Webhooks Stop Arriving
- Check that your endpoint returns 2xx and is reachable from the internet.
- Check your firewall or WAF is not blocking the requests.
- Reconcile pending transactions via the API after an outage rather than relying on retries alone.
Need help? Submit a support ticket or email pei@qiibee.com.