Skip to content

09-webhook-events.md

Latest commit

 

History

History
107 lines (83 loc) · 2.04 KB

09-webhook-events.md

File metadata and controls

107 lines (83 loc) · 2.04 KB

09 - Webhook Events

Overview

MultiWA delivers real-time events to your HTTP endpoints via webhooks.

Configuration

Per-Profile Webhook

POST /api/profiles/:id/webhook
{
  "url": "https://yourserver.com/webhook",
  "secret": "optional-hmac-secret",
  "events": ["message.received", "session.status"]
}

Global Webhook

POST /api/webhooks
{
  "url": "https://yourserver.com/webhook",
  "secret": "your-secret",
  "events": ["*"]
}

Event Types

Event Trigger
message.received Incoming message
message.sent Outgoing message confirmed
message.delivered Message delivered (✓✓)
message.read Message read (blue ✓✓)
session.connected WhatsApp connected
session.disconnected WhatsApp disconnected
session.qr New QR code generated

Payload Format

{
  "event": "message.received",
  "profileId": "profile-123",
  "timestamp": "2026-02-05T10:00:00.000Z",
  "data": {
    "id": "true_628xxx_3EB0ABC",
    "from": "628123456789@c.us",
    "body": "Hello!",
    "type": "chat",
    "hasMedia": false
  }
}

HMAC Verification

If you set a secret, verify the signature:

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return `sha256=${expected}` === signature;
}

// In your handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-multiwa-signature'];
  if (!verifyWebhook(req.body, signature, 'your-secret')) {
    return res.status(401).send('Invalid signature');
  }
  // Process event...
});

Retry Policy

Attempt Delay
1 Immediate
2 30 seconds
3 2 minutes
4 10 minutes
5 1 hour

After 5 failed attempts, the webhook is marked as failing.

← WebSocket API · Documentation Index · Messaging →