Building a Real-Time Notification System with SendAfrica Webhooks

Webhooks let your application receive real-time updates when SMS messages are delivered, failed, or clicked. This tutorial shows you how to build a complete notification system using SendAfrica webhooks.

What Are Webhooks?

Instead of repeatedly asking the API "has my message been delivered?" (polling), webhooks push updates to your server automatically. When something happens to an SMS message, SendAfrica sends an HTTP POST request to your endpoint.

Setting Up Your Webhook Endpoint

Express.js Example

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Verify webhook signature
function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === expected;
}

app.post('/webhooks/sms', (req, res) => {
  const signature = req.headers['x-sendafrica-signature'];
  
  if (!verifyWebhook(JSON.stringify(req.body), signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, message_id, status, to, delivered_at } = req.body;

  switch (event) {
    case 'sms.delivered':
      console.log(`✅ Message ${message_id} delivered to ${to}`);
      // Update database
      break;
    case 'sms.failed':
      console.log(`❌ Message ${message_id} failed: ${req.body.error}`);
      // Log failure, alert ops team
      break;
    case 'sms.clicked':
      console.log(`🔗 Link clicked in message ${message_id}`);
      // Track engagement
      break;
  }

  res.sendStatus(200);
});

app.listen(3000);

Building the Notification Dashboard

Database Schema

CREATE TABLE sms_events (
  id SERIAL PRIMARY KEY,
  message_id VARCHAR(255) NOT NULL,
  event VARCHAR(50) NOT NULL,
  to_number VARCHAR(20),
  details JSONB,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_sms_events_message ON sms_events(message_id);
CREATE INDEX idx_sms_events_created ON sms_events(created_at DESC);

Real-Time Updates with WebSockets

const { Server } = require('socket.io');
const io = new Server(server);

// When webhook arrives, broadcast to connected dashboards
app.post('/webhooks/sms', (req, res) => {
  const { event, message_id, status } = req.body;
  
  // Store in database
  db.query(
    'INSERT INTO sms_events (message_id, event, to_number, details) VALUES ($1, $2, $3, $4)',
    [message_id, event, req.body.to, JSON.stringify(req.body)]
  );

  // Broadcast to dashboard
  io.emit('sms:update', { message_id, event, status, timestamp: new Date() });
  
  res.sendStatus(200);
});

Monitoring and Alerting

Set up alerts for critical events:

• Delivery rate drops below 95%: Alert via Slack/PagerDuty
• Message failures spike: Automatic retry queue
• Webhook delivery fails: Secondary polling fallback

Best Practices

1. Always verify signatures to prevent spoofing
2. Return 200 quickly (< 5 seconds) — process asynchronously
3. Implement idempotency — webhooks may be retried
4. Log everything for debugging
5. Set up a dead letter queue for failed webhook processing

Production Checklist

• Webhook endpoint deployed with HTTPS
• Signature verification implemented
• Database events table created
• Alert thresholds configured
• Dead letter queue set up
• Load testing completed
• Monitoring dashboard live

Ready to build real-time notifications? Get your API key from SendAfrica.