Webhooks
Receive real-time notifications about SMS delivery status, OTP verification events, and bulk job progress. Webhooks eliminate the need for polling and enable event-driven architectures.
Real-time Updates
Get instant notifications for SMS delivery, OTP verification, and bulk job completion
Signature Verification
cryptographically signed payloads to verify webhook authenticity
Automatic Retries
Failed webhooks are retried with exponential backoff for 24 hours
Event Filtering
Subscribe to specific events to reduce noise and processing load
Advanced security measures for sensitive operations
- Payload signatures
- HTTPS enforcement
- IP whitelisting available
- 24-hour retry window
Authentication
Webhook URLs
- Must use HTTPS (HTTP not accepted in production)
- Should respond with 2xx status within 5 seconds
- Can be configured per event type or globally
- Test with our webhook simulator before going live
150ms
p95: 350ms
24h
Max 6 attempts
99.9%
Delivery success
12+
Filterable events
Webhook Events
Payload Examples
{"messageId": "MSG-1712499111","recipient": "233541234567","status": "DELIVERED","cost": 0.05,"providerStatus": "DELIVERED"}
Signature Verification
Always verify webhook signatures
| Header | Format | Description |
|---|---|---|
| X-Signature | sha256=hexdigest | HMAC-SHA256 signature |
| X-Signature-Version | 1 | Signature version for future compatibility |
| X-Webhook-ID | whk_123456789 | Unique webhook delivery ID |
| X-Timestamp | ISO 8601 | When the webhook was sent |
| X-Attempt | 1-6 | Current delivery attempt number |
Retry Policy
If your endpoint doesn't respond with a 2xx status within 5 seconds, we'll retry with exponential backoff for up to 24 hours.
| Attempt | Delay | Description |
|---|---|---|
| #1 | 5 seconds | Initial retry after failure |
| #2 | 30 seconds | Second attempt |
| #3 | 5 minutes | Third attempt |
| #4 | 30 minutes | Fourth attempt |
| #5 | 2 hours | Fifth attempt |
| #6 | 6 hours | Final attempt |
Timeout Recommendation
Test Your Webhook
This sends a test webhook to your endpoint with a valid signature header. Your endpoint should return a 2xx status within 5 seconds.
Configuration Examples
1. Navigate to Webhooks Settings
Dashboard → Settings → Webhooks
2. Add Endpoint URL
https://api.yourdomain.com/webhooks/sendexa
3. Select Events
Choose which events to subscribe to (sms.*, otp.*, bulk.*)
4. Generate Secret
Copy the webhook secret for signature verification
5. Send Test
Click "Send Test" to verify your endpoint
Best Practices
Respond Quickly
Always return 2xx status within 5 seconds. Process webhooks asynchronously.
Verify Signatures
Always verify webhook signatures to ensure they're from Sendexa.
Idempotent Processing
Handle duplicate webhooks gracefully using webhook-id for deduplication.
Log Everything
Keep audit logs of all webhook events for debugging and compliance.
Common Integration Patterns
Update Order Status
When SMS is delivered, update order status and notify customer via email
// Handle sms.delivered webhookasync function handleSMSDelivered(data) {const order = await Order.findByPhone(data.to);await order.update({ status: 'notification_sent' });await sendEmail(order.customerEmail, {subject: 'SMS Delivered',body: `Your order update was delivered to ${data.to}`});}
OTP Success Flow
On OTP verification, create user session and log audit trail
// Handle otp.verified webhookasync function handleOTPVerified(data) {const session = await Session.create({userId: data.metadata.userId,verifiedAt: data.verifiedAt,ipAddress: data.metadata.ipAddress});await AuditLog.create({action: 'otp_verified',userId: data.metadata.userId,details: {attempts: data.attemptsUsed,phone: data.phone}});return session;}
Campaign Analytics
Track delivery rates and update dashboards in real-time
// Handle multiple webhook typesclass CampaignAnalytics {constructor() {this.metrics = {sent: 0,delivered: 0,failed: 0,conversions: 0};}async handleWebhook(payload) {const { event, data } = payload;switch(event) {case 'sms.sent':this.metrics.sent++;await this.updateRedis('campaign:sent', 1);break;case 'sms.delivered':this.metrics.delivered++;await this.updateDeliveryRate(data.campaignId);break;case 'sms.failed':this.metrics.failed++;await this.alertOnHighFailure(data);break;}await this.updateDashboard();}}
Troubleshooting
Webhook not receiving events
- Verify URL is publicly accessible (not localhost)
- Check SSL certificate is valid (not self-signed)
- Confirm webhook is active in dashboard
- Check if events are properly subscribed
- Look for IP blocks in firewall logs
Signature verification failing
- Ensure you're using the raw request body, not parsed JSON
- Check that webhook secret is correctly copied
- Verify you're using the correct signature header
- Make sure payload isn't being modified in transit
- Test with our signature verification tool
Receiving duplicate webhooks
- Implement idempotency using X-Webhook-ID header
- Check if your endpoint is responding with 2xx within timeout
- Verify you're not returning redirects (3xx)
- Store processed webhook IDs for 24 hours
Webhook timeout errors
- Process webhooks asynchronously (queue them)
- Return 200 immediately, then process in background
- Optimize database queries in webhook handler
- Consider using a job queue (Bull, Sidekiq, etc.)
Monitoring & Alerts
Webhook Health Dashboard
Monitor delivery rates, latency, and failure rates
99.9%
Delivery Rate
150ms
Avg Latency
0.1%
Failure Rate
Set up alerts
- Failure rate exceeds 5% in 5 minutes
- Endpoint latency exceeds 3 seconds
- No successful deliveries in 15 minutes
- Retry queue exceeds 1000 events
IP Whitelisting
Sendexa Webhook IPs
Add these IPs to your firewall whitelist to ensure you only accept webhooks from Sendexa:
52.215.68.14252.31.139.17552.48.225.109IPs are subject to change. Subscribe to our IP feed for updates.
Webhook Rate Limits
100/s
Max webhooks per second
Per account
5s
Timeout limit
Must respond within
24h
Retry window
Max 6 attempts
Webhook Implementation Checklist
- HTTPS endpoint configured
- Signature verification implemented
- Idempotency handling with webhook-id
- Async processing implemented
- Monitoring & alerts configured
- IP whitelist updated
Need help with webhooks?
Our team can help you debug webhook issues and optimize your integration:
- Email: webhooks@sendexa.co
- Discord: #webhook-support
- Documentation: /docs/webhooks/examples
- Status: https://status.sendexa.co