Real-time events
for your systems.
Subscribe to webhook events to keep your HRIS, CRM, or custom systems in sync with every reward lifecycle event.
Setup
01
Add your endpoint URL
Go to Settings → Webhooks in your dashboard. Paste your HTTPS endpoint URL.
02
Select events to subscribe
Choose which event types your endpoint should receive.
03
Verify the signature
Every POST includes an X-Ribi-Signature header. Verify it with your webhook secret to confirm authenticity.
04
Respond with 200
Return a 200 OK within 5 seconds. We retry with exponential backoff on failure (up to 5 attempts).
Example payload
{
"event": "reward.redeemed",
"created_at": "2025-11-28T14:23:00Z",
"data": {
"reward_id": "rwd_01jg4k92xm",
"recipient_email": "ada@company.ng",
"type": "choice_card",
"amount": 15000,
"currency": "NGN",
"selected_brand": "ShopRite",
"redeemed_at": "2025-11-28T14:23:00Z"
}
}Available events
reward.sent
Triggered when a reward is successfully dispatched to a recipient.
{ reward_id, recipient_email, type, amount, currency, sent_at }
reward.opened
Triggered when the recipient opens their reward email for the first time.
{ reward_id, recipient_email, opened_at }
reward.redeemed
Triggered when the recipient completes redemption and selects their reward.
{ reward_id, recipient_email, selected_brand, redeemed_at }
reward.expired
Triggered when a reward passes its expiry date without being redeemed.
{ reward_id, recipient_email, expired_at }
reward.cancelled
Triggered when a reward is manually cancelled before redemption.
{ reward_id, cancelled_by, cancelled_at }
wallet.low_balance
Triggered when your wallet balance drops below your configured threshold.
{ wallet_id, current_balance, threshold, currency }
Need help setting up webhooks?
Check the API docs or contact our developer support team.
View API Docs →