Set up webhooks

Webhooks push events from WaSMS to your server the moment they happen — no polling needed.

Events

• message.received — inbound message
• message.sent — your outbound queued
• message.delivered — reached recipient
• message.read — recipient opened it
• message.failed — delivery failed
• contact.created — new contact added
• conversation.assigned — team member picked it up

1. Create your endpoint

app.post('/wasms-webhook', (req, res) => {
  console.log(req.body.event, req.body.data);
  res.sendStatus(200);
});

2. Register in WaSMS

1. Go to Settings → Webhooks.
2. Click + Add webhook.
3. Paste URL, pick events.
4. Copy the signing secret.

3. Verify signature

const sig = req.headers['x-wasms-signature'];
const expected = crypto.createHmac('sha256', SECRET)
  .update(JSON.stringify(req.body)).digest('hex');
if (sig !== expected) return res.sendStatus(401);

Payload shape

{
  "event": "message.received",
  "timestamp": "2026-05-31T10:23:45Z",
  "data": {
    "message_id": "msg_xyz",
    "channel": "whatsapp",
    "from": "+923001234567",
    "text": "Hi"
  }
}

Retry policy

If your endpoint returns non-2xx or times out (10s), we retry: 30s, 2min, 10min, 1h, 6h. After 5 failures the webhook is paused.

Best practices

• Return 200 fast — queue work async.
• Use message_id for idempotency.
• Verify signature.
• HTTPS only.