Receive real-time notifications when gifts are delivered, redeemed, or expire. Keep your systems in sync automatically.
Webhooks push real-time updates to your application instead of polling our API
Get notified within seconds when a gift status changes. No need to poll our API repeatedly.
Save API quota and reduce latency. We push updates to you instead of you checking for them.
Automatic retries with exponential backoff. We'll keep trying until your endpoint acknowledges receipt.
Subscribe to the events that matter for your integration
gift.deliveredReal-timeFired when a gift is successfully delivered to the recipient
gift.redeemedReal-timeFired when recipient redeems their gift
gift.failedReal-timeFired when gift delivery fails
gift.expiredDaily batchFired when an unredeemed gift expires
address.collectedReal-timeFired when recipient provides shipping address for gift box
Get webhooks running in 5 minutes
Set up a POST endpoint on your server to receive webhook events:
// Example: Node.js / Express
app.post('/webhooks/ribirewards', (req, res) => {
const event = req.body;
// Verify webhook signature
const signature = req.headers['x-ribi-signature'];
if (!verifySignature(event, signature)) {
return res.status(401).send('Invalid signature');
}
// Handle the event
switch(event.type) {
case 'gift.delivered':
handleGiftDelivered(event.data);
break;
case 'gift.redeemed':
handleGiftRedeemed(event.data);
break;
// ... other events
}
// Return 200 to acknowledge receipt
res.status(200).send('Received');
});Add your endpoint URL in the RibiRewards dashboard or via API:
POST https://api.ribirewards.com/v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"url": "https://your-domain.com/webhooks/ribirewards",
"events": [
"gift.delivered",
"gift.redeemed",
"gift.failed"
],
"description": "Production webhook"
}Always verify that webhooks came from RibiRewards:
const crypto = require('crypto');
function verifySignature(payload, signature) {
const expectedSignature = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(JSON.stringify(payload))
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}Here's what you'll receive when a gift is delivered
{
"id": "evt_1234567890",
"type": "gift.delivered",
"created_at": "2026-02-04T15:30:00Z",
"data": {
"gift_id": "gift_abc123",
"recipient": {
"email": "john@example.com",
"name": "John Doe"
},
"gift_type": "choice_card",
"amount": 100,
"currency": "USD",
"category": "coffee",
"delivered_at": "2026-02-04T15:30:00Z",
"redemption_url": "https://redeem.ribirewards.com/abc123",
"expires_at": "2026-05-04T15:30:00Z"
}
}Process webhooks asynchronously. Return 200 within 5 seconds, then handle the event in a background job.
Due to retries, you may receive the same event twice. Use the event ID to prevent duplicate processing.
Set up alerts for failed webhooks. Check the dashboard for delivery status and retry history.
Webhook URLs must use HTTPS. We won't send webhooks to unencrypted endpoints.
Our developer support team can help you integrate webhooks and troubleshoot any issues.