Webhooks
Receive real-time notifications when events occur in your incentive program.
Webhooks
Webhooks allow your application to receive real-time notifications when events occur in Incentable.
Setting Up Webhooks
- Go to Settings → Webhooks in your admin dashboard
- Click Add Endpoint
- Enter your endpoint URL
- Select the events you want to receive
- Save and copy your webhook secret
Webhook Payload
All webhooks are sent as POST requests with a JSON payload:
{
"id": "evt_abc123",
"type": "points.awarded",
"created_at": "2024-06-15T14:30:00Z",
"data": {
// Event-specific data
}
}
Verifying Webhooks
Every webhook includes a signature in the X-Incentable-Signature header. Verify this to ensure the webhook came from Incentable.
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
Always verify webhook signatures in production to prevent unauthorized requests.
Available Events
Points Events
| Event | Description |
|---|---|
points.awarded | Points were added to a member's balance |
points.deducted | Points were removed from a member's balance |
points.expired | Points expired due to inactivity |
Example: points.awarded
{
"id": "evt_abc123",
"type": "points.awarded",
"created_at": "2024-06-15T14:30:00Z",
"data": {
"transaction_id": "txn_def456",
"member_id": "mem_abc123",
"points": 500,
"reason": "Q2 Sales Target",
"new_balance": 5500
}
}
Member Events
| Event | Description |
|---|---|
member.created | A new member was added |
member.updated | Member details were changed |
member.tier_changed | Member moved to a different tier |
Example: member.tier_changed
{
"id": "evt_xyz789",
"type": "member.tier_changed",
"created_at": "2024-06-15T14:30:00Z",
"data": {
"member_id": "mem_abc123",
"previous_tier": "Silver",
"new_tier": "Gold",
"reason": "Points threshold reached"
}
}
Reward Events
| Event | Description |
|---|---|
reward.redeemed | A member redeemed a reward |
order.shipped | A physical reward was shipped |
order.delivered | A reward was delivered |
Example: reward.redeemed
{
"id": "evt_order123",
"type": "reward.redeemed",
"created_at": "2024-06-15T14:35:00Z",
"data": {
"order_id": "ord_789xyz",
"member_id": "mem_abc123",
"reward_id": "rwd_001",
"reward_name": "Amazon Gift Card $25",
"points_spent": 2500
}
}
Leaderboard Events
| Event | Description |
|---|---|
leaderboard.position_changed | A member's ranking changed |
leaderboard.period_ended | A competition period ended |
Retry Policy
If your endpoint returns an error (non-2xx status code), we'll retry the webhook:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 24 hours |
After 5 failed attempts, the webhook will be marked as failed and you'll receive an email notification.
Testing Webhooks
Use the Send Test Event button in your dashboard to send sample payloads to your endpoint during development.
You can also use tools like ngrok to expose your local development server for webhook testing.