Sendexa LogoDocs

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.

Webhook Integration Tutorial (5:30 mins)
How to integrate webhooks with Sendexa API
5:30

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

High Security
HIGH

Advanced security measures for sensitive operations

  • Payload signatures
  • HTTPS enforcement
  • IP whitelisting available
  • 24-hour retry window
Avg Delivery Time

150ms

p95: 350ms

Retry Duration

24h

Max 6 attempts

Success Rate

99.9%

Delivery success

Event Types

12+

Filterable events

Webhook Configuration & Events
v1

Webhook Events

Payload Examples

{
"messageId": "MSG-1712499111",
"recipient": "233541234567",
"status": "DELIVERED",
"cost": 0.05,
"providerStatus": "DELIVERED"
}

Signature Verification

HeaderFormatDescription
X-Signaturesha256=hexdigestHMAC-SHA256 signature
X-Signature-Version1Signature version for future compatibility
X-Webhook-IDwhk_123456789Unique webhook delivery ID
X-TimestampISO 8601When the webhook was sent
X-Attempt1-6Current 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.

AttemptDelayDescription
#15 secondsInitial retry after failure
#230 secondsSecond attempt
#35 minutesThird attempt
#430 minutesFourth attempt
#52 hoursFifth attempt
#66 hoursFinal attempt

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 webhook
async 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 webhook
async 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 types
class 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

24h rolling

99.9%

Delivery Rate

150ms

Avg Latency

0.1%

Failure Rate

IP Whitelisting

Sendexa Webhook IPs

Add these IPs to your firewall whitelist to ensure you only accept webhooks from Sendexa:

52.215.68.142
Primary
52.31.139.175
Secondary
52.48.225.109
Backup

IPs 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