Webhook payloads

npm install @open-wa/integration-webhook@5.1.0

// wa.config.mjs
const webhookSecret = process.env.OPEN_WA_WEBHOOK_SECRET?.trim();
if (!webhookSecret) throw new Error('OPEN_WA_WEBHOOK_SECRET is required');

export default {
  sessionId: 'sales',
  host: '127.0.0.1',
  port: 8080,
  plugins: ['@open-wa/integration-webhook'],
  pluginConfig: {
    webhook: {
      url: 'https://receiver.example/webhooks/open-wa',
      events: ['message.received', 'session.state.changed'],
      headers: { 'X-Webhook-Secret': webhookSecret },
      concurrency: 10,
      queueCapacity: 1000,
      overload: 'backpressure',
      retries: 3,
      retryDelay: 1000,
      timeout: 30000,
      // Set enabled: true only when this process can write the journal path.
      durability: {
        enabled: false,
        path: '.openwa/webhook-deliveries.sqlite',
        replayLimit: 1000,
      },
    },
  },
};

export OPEN_WA_WEBHOOK_SECRET='use-a-long-random-value'
npx @open-wa/wa-automate@5.1.0 --config ./wa.config.mjs --session-id sales --host 127.0.0.1 --port 8080

{
  "webhookId": "0f5d6a52-2ff2-43d5-9d0d-9c0c8dd5f9d1",
  "sessionId": "sales",
  "event": "message.received",
  "payload": {
    "message": {
      "id": "false_1234567890@c.us_ABC123",
      "from": "1234567890@c.us",
      "to": "0987654321@c.us",
      "body": "Hello, I need help with my order",
      "caption": "",
      "type": "chat",
      "timestamp": 1700000000,
      "fromMe": false,
      "isGroupMsg": false,
      "isMedia": false
    }
  },
  "timestamp": 1700000000123
}

// receiver.mjs
import express from 'express';
import Database from 'better-sqlite3';
import { createHash, timingSafeEqual } from 'node:crypto';

const expectedSecret = process.env.OPEN_WA_WEBHOOK_SECRET?.trim();
if (!expectedSecret) {
  throw new Error('OPEN_WA_WEBHOOK_SECRET must be set before the receiver starts');
}
const expectedBytes = Buffer.from(expectedSecret, 'utf8');
const inbox = new Database('./openwa-webhook-inbox.sqlite');
inbox.exec(`
  CREATE TABLE IF NOT EXISTS webhook_inbox (
    idempotency_key TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    event TEXT NOT NULL,
    received_at INTEGER NOT NULL,
    envelope TEXT NOT NULL
  )
`);
const insertInbox = inbox.prepare(`
  INSERT OR IGNORE INTO webhook_inbox
    (idempotency_key, session_id, event, received_at, envelope)
  VALUES (?, ?, ?, ?, ?)
`);

const app = express();
const rawBodies = new WeakMap();
const allowRawDiagnostics = process.env.NODE_ENV !== 'production'
  && process.env.DEBUG_WEBHOOK_RAW === '1';

function authenticate(req, res, next) {
  const supplied = req.get('X-Webhook-Secret');
  if (!supplied || supplied.length !== expectedSecret.length) {
    return res.status(401).send('Unauthorized');
  }
  const suppliedBytes = Buffer.from(supplied, 'utf8');
  if (suppliedBytes.length !== expectedBytes.length || !timingSafeEqual(suppliedBytes, expectedBytes)) {
    return res.status(401).send('Unauthorized');
  }
  next();
}

function isRecord(value) {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}

function parseEnvelope(value) {
  if (!isRecord(value)) return null;
  if (typeof value.webhookId !== 'string' || !value.webhookId) return null;
  if (typeof value.sessionId !== 'string' || !value.sessionId) return null;
  if (typeof value.event !== 'string' || !value.event) return null;
  if (typeof value.timestamp !== 'number' || !Number.isFinite(value.timestamp)) return null;
  if (!('payload' in value)) return null;
  return value;
}

app.post('/webhooks/open-wa', authenticate, express.json({
  limit: '2mb',
  // Temporary local diagnosis only. This is disabled when NODE_ENV is production.
  verify: (req, _res, buffer) => {
    if (allowRawDiagnostics) rawBodies.set(req, buffer.toString('utf8'));
  },
}), (req, res) => {
  const envelope = parseEnvelope(req.body);
  if (!envelope) return res.status(400).send('Invalid open-wa webhook envelope');

  if (allowRawDiagnostics) {
    console.warn('[LOCAL ONLY] raw webhook body:', rawBodies.get(req) ?? '(empty body)');
  }

  const messageId = envelope.payload?.message?.id;
  const idempotencyKey = req.get('Idempotency-Key')
    || (typeof messageId === 'string' && messageId
      ? `${envelope.sessionId}:${envelope.event}:${messageId}`
      : createHash('sha256').update(JSON.stringify(envelope)).digest('hex'));

  // Insert the authenticated event before acknowledging it. A duplicate key is a no-op.
  const result = insertInbox.run(
    idempotencyKey,
    envelope.sessionId,
    envelope.event,
    Date.now(),
    JSON.stringify(envelope),
  );
  console.info('webhook inbox updated', {
    sessionId: envelope.sessionId,
    event: envelope.event,
    duplicate: result.changes === 0,
  });
  res.sendStatus(204);
});

app.use((error, _req, res, _next) => {
  if (error?.type === 'entity.too.large') return res.status(413).send('Webhook body too large');
  if (error?.type === 'entity.parse.failed') return res.status(400).send('Malformed JSON');
  console.error('webhook receiver error', { name: error?.name ?? 'Error' });
  res.status(500).send('Webhook receiver error');
});

app.listen(3000, () => console.log('Webhook receiver listening on http://localhost:3000'));

npm install express better-sqlite3
export OPEN_WA_WEBHOOK_SECRET='use-a-long-random-value'
node receiver.mjs

# Missing secret: HTTP 401
curl -i -X POST http://localhost:3000/webhooks/open-wa \
  -H 'Content-Type: application/json' \
  -d '{}'

# Authenticated but malformed JSON: HTTP 400
curl -i -X POST http://localhost:3000/webhooks/open-wa \
  -H 'Content-Type: application/json' \
  -H "X-Webhook-Secret: $OPEN_WA_WEBHOOK_SECRET" \
  -d '{'

# Valid envelope: HTTP 204
curl -i -X POST http://localhost:3000/webhooks/open-wa \
  -H 'Content-Type: application/json' \
  -H "X-Webhook-Secret: $OPEN_WA_WEBHOOK_SECRET" \
  -d '{"webhookId":"local-test","sessionId":"sales","event":"message.received","payload":{"message":{"id":"local-1","from":"1234567890@c.us","body":"Hello"}},"timestamp":1700000000123}'