Webhook Best Practices

This guide covers production-ready patterns for receiving and processing SendAPI webhook events reliably.

Respond Quickly

Your webhook endpoint should return a 200 OK response within 10 seconds — SendAPI's HTTP client times out after 10s and treats the delivery as failed. If your processing takes longer, acknowledge the event immediately and offload heavy work to a background queue.

javascript

// ✅ Good — acknowledge immediately, process later
app.post('/webhook', (req, res) => {
  const event = req.body;
  queue.add('process-webhook', event); // Background job
  res.status(200).json({ received: true });
});

// ❌ Bad — blocks until processing completes
app.post('/webhook', async (req, res) => {
  await processEvent(req.body);  // Might take 10+ seconds
  res.json({ received: true });
});

Handle Duplicates (Idempotency)

SendAPI may deliver the same event more than once (e.g., during retries). Use the event id to deduplicate:

javascript

app.post('/webhook', async (req, res) => {
  const eventId = req.body.id;

  // Check if we've already processed this event
  const exists = await db.webhookEvents.findOne({ eventId });
  if (exists) {
    return res.status(200).json({ received: true }); // Already processed
  }

  // Store and process
  await db.webhookEvents.create({ eventId, data: req.body });
  await processEvent(req.body);

  res.status(200).json({ received: true });
});

Verify Event Authenticity

When SDK support is available, verify webhook signatures to ensure events are genuinely from SendAPI and haven't been tampered with. Until then, restrict your webhook endpoint by IP or use a secret URL path.

Event Types

Event	Description
`sms.delivered`	SMS was successfully delivered to the handset
`sms.failed`	SMS delivery failed
`whatsapp.message.sent`	WhatsApp message was sent
`whatsapp.message.delivered`	WhatsApp message was delivered
`whatsapp.message.read`	WhatsApp message was read
`whatsapp.message.received`	Inbound WhatsApp message received
`whatsapp.session.connected`	WhatsApp session paired successfully
`whatsapp.session.disconnected`	WhatsApp session lost connection
`email.delivered`	Email was delivered to the inbox
`email.opened`	Recipient opened the email
`email.clicked`	Recipient clicked a link
`email.bounced`	Email bounced (hard or soft)

Retry Policy

If your endpoint returns a non-2xx status code or times out (10 seconds), SendAPI retries with exponential backoff. 4 attempts total:

Attempt	Delay since previous attempt
1 (initial)	Immediate
2	5 seconds
3	30 seconds
4	2 minutes

After 4 failed attempts, the delivery is marked failed. You can inspect or re-trigger it via GET /v1/webhooks/{id}/deliveries.

Webhook Best Practices ​

Respond Quickly ​

Handle Duplicates (Idempotency) ​

Verify Event Authenticity ​

Event Types ​

Retry Policy ​

Related ​