Before implementing a receiver, review signing and verification and delivery and retries.
Complete Workflow Example
1. Create Webhook
curl -X POST https://sso.example.com/api/organizations/acme-corp/webhooks \
-H "Authorization: Bearer {jwt}" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Events",
"url": "https://api.acme.com/webhooks/sso",
"events": ["user.login.success", "user.signup.success"]
}'
2. Implement Webhook Endpoint
// Express.js webhook handler
app.post('/webhooks/sso', express.json(), (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = req.body;
// Verify signature
if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process event
switch (payload.event) {
case 'user.login.success':
console.log(`User ${payload.actor_email} logged in`);
break;
case 'user.signup.success':
console.log(`New user ${payload.actor_email} signed up`);
// Send welcome email, create account in CRM, etc.
break;
}
res.status(200).json({ status: 'received' });
});
3. Monitor Deliveries
curl -X GET "https://sso.example.com/api/organizations/acme-corp/webhooks/{webhook_id}/deliveries?page=1&limit=50" \
-H "Authorization: Bearer {jwt}"
4. Handle Failed Deliveries
# Check for failed deliveries
curl -X GET "https://sso.example.com/api/organizations/acme-corp/webhooks/{webhook_id}/deliveries?delivered=false" \
-H "Authorization: Bearer {jwt}"
# Review error messages and fix endpoint
# Optionally disable webhook while fixing
curl -X PATCH https://sso.example.com/api/organizations/acme-corp/webhooks/{webhook_id} \
-H "Authorization: Bearer {jwt}" \
-H "Content-Type: application/json" \
-d '{ "is_active": false }'
Best Practices
Webhook Design
- Subscribe only to events you need to reduce traffic
- Use descriptive webhook names for easy identification
- Implement proper error handling and logging
- Return 2xx status codes quickly (process asynchronously)
- Use signature verification for security
Endpoint Implementation
- Implement idempotency using delivery IDs
- Process webhooks in background jobs/queues
- Log all webhook deliveries for debugging
- Return non-2xx only for invalid requests
- Implement rate limiting and request validation
Monitoring & Maintenance
- Monitor delivery success rates
- Set up alerts for failed deliveries
- Review delivery history regularly
- Test webhook endpoints before enabling
- Document your webhook integrations
Security
- Always verify webhook signatures
- Validate timestamps to limit the replay window and persist delivery IDs for deduplication
- Use HTTPS endpoints only
- Store webhook secrets securely
- Implement IP allowlisting if possible
- Rate limit webhook endpoints