DEV Community

Cover image for WhatsApp Webhooks: Complete Developer Guide with Omdaa API
Omdaa API
Omdaa API

Posted on Edited on Originally published at omdaa.com

WhatsApp Webhooks: Complete Developer Guide with Omdaa API

#webhooks #whatsapp #nodejs #tutorial

WhatsApp Webhooks: Complete Developer Guide with Omdaa API

Webhooks turn WhatsApp into a real-time event stream for your backend, n8n, Zapier, or AI agents. This guide uses Omdaa API — free forever, no message limits.

Series: Free Forever WhatsApp Dev · Docs: omdaa.com/whatsapp-webhooks

Why webhooks?

Polling is slow and wasteful. With webhooks you get instant events:

  • message / message.received — inbound messages
  • session — connected / disconnected
  • Delivery & status updates for outbound messages

Perfect for n8n, Zapier, custom Node servers, or Cursor MCP.

Step 1: Install the SDK 

npm install @omdaafreeapi/omdaa-api-client
Enter fullscreen mode Exit fullscreen mode

Step 2: Set your webhook URL 

const { OmdaaClient } = require('@omdaafreeapi/omdaa-api-client');

const client = new OmdaaClient({ apiKey: process.env.OMDAA_API_KEY });

await client.webhooks.set({
  url: 'https://your-server.com/webhook',
  events: ['message.received', 'session'],
  enabled: true,
});

await client.webhooks.test();
Enter fullscreen mode Exit fullscreen mode

cURL alternative:

curl -X POST "https://omdaa.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["message.received", "session"],
    "enabled": true
  }'
Enter fullscreen mode Exit fullscreen mode

Or configure from Dashboard → Webhooks / MCP tool set_webhook.

Step 3: Verify signatures (recommended)

Omdaa signs payloads with HMAC-SHA256. Validate before processing:

X-Webhook-Signature: sha256=<hmac>
Enter fullscreen mode Exit fullscreen mode

Compute HMAC-SHA256 over the raw request body with your webhook secret. Reject mismatches with 401.

Step 4: Handle events 

app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  // verify signature on req.body (Buffer) first
  const payload = JSON.parse(req.body.toString('utf8'));
  const { event, data } = payload;

  if (event === 'message.received' || event?.includes('message')) {
    console.log('From:', data?.from, 'Text:', data?.text || data?.message?.body);
  }

  res.sendStatus(200); // ack fast — process async
});
Enter fullscreen mode Exit fullscreen mode

Built-in reliability

Feature Benefit
Retry queue Exponential backoff on 5xx / timeouts
Circuit breaker Auto-pauses failing endpoints
Rate limiting Protects your receiver
Test endpoint client.webhooks.test() smoke check

Connect to n8n / Zapier

  1. Import integrations/n8n/omdaa-whatsapp-inbound.workflow.json
  2. Point webhook URL to https://omdaa.com/n8n/webhook/omdaa-whatsapp
  3. Or use a Zapier Catch Hook — see the Zapier tutorial

Troubleshooting

Issue Fix
No events Confirm webhook enabled: true + session connected
404 on Zapier/n8n Workflow / Zap must be active
Empty body Read raw body before JSON middleware
Signature fail HMAC over raw bytes, not re-serialized JSON

Next steps

  1. Create free account
  2. Connect WhatsApp session
  3. Add Omdaa AI auto-replies
  4. Cursor MCP catalog

Omdaa API — Free Forever. Real-time WhatsApp events without Meta Cloud API complexity.

Top comments (0)