WhatsApp Webhook Setup: Real-Time Message Processing

curl -X PUT https://api.wsapi.chat/account/instances/{instanceId}/settings \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.com/webhooks/whatsapp",
    "eventSigningSecret": "a-long-random-string",
    "eventFilters": ["message", "message_read", "user_presence", "group"]
  }'

import express from 'express';
import crypto from 'crypto';

const app = express();
const SIGNING_SECRET = process.env.WSAPI_SIGNING_SECRET;

// Fail closed, at startup: with no secret configured nothing is signed and
// nothing can be verified, and a receiver that skips the check looks exactly
// like one that passes it. Better to refuse to boot than to accept anything.
if (!SIGNING_SECRET) {
  throw new Error('WSAPI_SIGNING_SECRET is not set: configure a signing secret on your instance first');
}

// The signature covers the bytes WSAPI sent, so the body is read raw and
// parsed only after the check. express.json() would re-serialise it and
// every signature would fail.
app.post('/webhooks/whatsapp', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature(req.body, req.header('X-Webhook-Signature'))) {
    return res.sendStatus(401);
  }

  let payload;
  try {
    payload = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }

  const { eventType, eventData } = payload;

  switch (eventType) {
    case 'message': {
      const direction = eventData.sender.isMe ? 'SENT' : 'RECV';
      console.log(`[${direction}] ${eventData.sender.id}: ${eventData.text ?? '[' + eventData.type + ']'}`);
      break;
    }
    case 'message_read':
      console.log(`[RECEIPT] ${eventData.receiptType} in ${eventData.chatId}`);
      break;
    case 'user_presence':
      console.log(`[PRESENCE] ${eventData.id} is ${eventData.status}`);
      break;
    case 'group':
      console.log(`[GROUP] ${eventData.id} changed`);
      break;
  }

  res.sendStatus(200);
});

function verifySignature(rawBody, header) {
  if (!header) return false;

  const expected =
    'sha256=' + crypto.createHmac('sha256', SIGNING_SECRET).update(rawBody).digest('hex');

  // timingSafeEqual throws when the two buffers differ in length, which is
  // what a forged signature usually looks like, so compare lengths first.
  if (expected.length !== header.length) return false;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

app.listen(3000, () => console.log('Webhook server running on port 3000'));

import hashlib
import hmac
import json
import os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
# Fail closed at startup: no secret means nothing is verified.
SIGNING_SECRET = os.environ["WSAPI_SIGNING_SECRET"]

@app.post("/webhooks/whatsapp")
async def webhook(request: Request):
    raw = await request.body()          # the signature covers these bytes
    signature = request.headers.get("X-Webhook-Signature", "")

    expected = "sha256=" + hmac.new(
        SIGNING_SECRET.encode(), raw, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    payload = json.loads(raw)
    event_type = payload["eventType"]
    data = payload["eventData"]

    if event_type == "message":
        direction = "SENT" if data["sender"]["isMe"] else "RECV"
        print(f"[{direction}] {data['sender']['id']}: {data.get('text', '[' + data['type'] + ']')}")

    elif event_type == "message_read":
        print(f"[RECEIPT] {data['receiptType']} in {data['chatId']}")

    return {"status": "ok"}

// npm install eventsource
import { EventSource } from 'eventsource';

// The stream authenticates with the same two headers as the REST API. The
// browser's built-in EventSource cannot send headers, so this runs in Node
// and injects them through a custom fetch.
const stream = new EventSource('https://api.wsapi.chat/events/stream', {
  fetch: (url, init) =>
    fetch(url, {
      ...init,
      headers: {
        ...init.headers,
        'x-api-key': process.env.WSAPI_KEY,
        'x-instance-id': process.env.INSTANCE_ID,
      },
    }),
});

stream.onmessage = (e) => {
  const { eventType, eventData } = JSON.parse(e.data);

  if (eventType === 'message') {
    console.log('New message:', eventData.sender.id, eventData.text);
  }
};

stream.onerror = () => {
  console.log('Connection lost, reconnecting...');
};

import json
import os
import requests

with requests.get(
    "https://api.wsapi.chat/events/stream",
    headers={
        "x-api-key": os.environ["WSAPI_KEY"],
        "x-instance-id": os.environ["INSTANCE_ID"],
    },
    stream=True,
) as response:
    response.raise_for_status()

    for line in response.iter_lines():
        if not line.startswith(b"data: "):
            continue

        payload = json.loads(line[len(b"data: "):])
        print(payload["eventType"], payload["eventData"])