open-wa logoopen-wa

Receive webhooks

Forward incoming WhatsApp messages and other events to your own backend over HTTP, and store them safely.

Receive webhooks

Use a webhook when a backend, CRM, helpdesk or no-code tool should receive WhatsApp events over HTTP. open-wa POSTs each event to your URL; your receiver checks the secret, stores the event and returns 2xx. If your code runs in Node.js next to the session, onMessage is simpler; see receive messages for the choice.

Turn on delivery

Webhooks come from the @open-wa/integration-webhook plugin, loaded from your config file. The --webhook command-line flag is accepted but doesn't set up delivery, so use the config below.

If you generated your project with npm init @open-wa@latest and chose Webhooks, the plugin is already in wa.config.js and reads WEBHOOK_URL from .env. Otherwise install it next to the Easy API:

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

Then add it to wa.config.js in the directory you start the Easy API from:

wa.config.js
const webhookSecret = process.env.WEBHOOK_SECRET?.trim();
if (!webhookSecret) throw new Error('Set WEBHOOK_SECRET before starting open-wa');

export default {
  sessionId: 'sales',
  host: '127.0.0.1',
  apiKey: process.env.WA_API_KEY,
  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 },
    },
  },
};

Start your receiver first, then open-wa:

export WEBHOOK_SECRET='use-a-long-random-value'
npx @open-wa/wa-automate

The Easy API finds wa.config.js on its own and listens on port 8080. The same plugins and pluginConfig options work when you pass them to create() in the SDK.

The envelope

Every delivery is a JSON body with the same outer fields. payload holds the event itself.

{
  "webhookId": "0f5d6a52-2ff2-43d5-9d0d-9c0c8dd5f9d1",
  "sessionId": "sales",
  "event": "message.received",
  "payload": {
    "message": {
      "id": "false_447700900123@c.us_3EB0C7D5E4A1B2",
      "from": "447700900123@c.us",
      "body": "Hello, I need help with my order",
      "type": "chat",
      "timestamp": 1763560000,
      "fromMe": false,
      "isGroupMsg": false
    }
  },
  "timestamp": 1763560000123
}
You wantRead
The sender, to reply topayload.message.from
The textpayload.message.body, or payload.message.caption for media
A key to ignore duplicatespayload.message.id, or the Idempotency-Key header when durability is on

webhookId is fixed for the life of the process, so it can't tell two events apart. These events are the ones most integrations use:

EventPayload
message.receivedpayload.message for an incoming message
message.anypayload.message for incoming and outgoing messages
message.deletedpayload.messageId, payload.chatId and optional payload.by
ack.changedpayload.ack with the delivery or read state
session.state.changedpayload.details.prev and payload.details.next
group.participants.changed.globalpayload.change with who joined or left

The event contracts and the AsyncAPI document describe every event.

Run a receiver

This Express receiver checks the secret before it reads the body, limits the body to 2 MB, stores each event once in SQLite and returns 204. Do slower work, such as calling an AI model or a CRM, after the response.

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

const secret = process.env.WEBHOOK_SECRET?.trim();
if (!secret) throw new Error('Set WEBHOOK_SECRET before starting the receiver');
const secretBytes = Buffer.from(secret, 'utf8');

const db = new Database('./webhook-inbox.sqlite');
db.exec(`CREATE TABLE IF NOT EXISTS 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 insert = db.prepare('INSERT OR IGNORE INTO inbox VALUES (?, ?, ?, ?, ?)');

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

function isEnvelope(value) {
  return value && typeof value === 'object'
    && typeof value.sessionId === 'string' && value.sessionId
    && typeof value.event === 'string' && value.event
    && typeof value.timestamp === 'number'
    && 'payload' in value;
}

const app = express();

app.post('/webhooks/open-wa', checkSecret, express.json({ limit: '2mb' }), (req, res) => {
  const envelope = req.body;
  if (!isEnvelope(envelope)) return res.status(400).send('Not an open-wa webhook');

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

  // Store the event before acknowledging it. A repeated key is ignored.
  insert.run(key, envelope.sessionId, envelope.event, Date.now(), JSON.stringify(envelope));
  res.sendStatus(204);
});

app.use((error, _req, res, _next) => {
  if (error?.type === 'entity.too.large') return res.status(413).send('Body too large');
  if (error?.type === 'entity.parse.failed') return res.status(400).send('Malformed JSON');
  res.status(500).send('Receiver error');
});

app.listen(3000, () => console.log('Receiver listening on http://localhost:3000 (on your machine)'));
npm install express better-sqlite3
export WEBHOOK_SECRET='use-a-long-random-value'
node receiver.mjs

Before you connect WhatsApp, check that it rejects bad requests and accepts a good one:

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

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

The plugin sends your configured headers as they are and doesn't sign the body. If your gateway adds an HMAC signature, verify it against the raw body before parsing. For Zapier, Make or n8n, point the webhook URL at the tool's webhook trigger and map the fields from the table above.

Delivery and retries

A delivery succeeds when your receiver returns any 2xx status. Network errors, timeouts and other statuses are retried with exponential backoff. These are the defaults, all set under pluginConfig.webhook:

SettingDefaultWhat it does
events'all'Event names to forward, or 'all'
concurrency10Requests in flight at once
queueCapacity1000Deliveries waiting in memory
overload'backpressure'backpressure waits for room when the queue is full; dropping rejects new deliveries
timeout30000Milliseconds before a request is abandoned
retries3Retries after the first attempt, at 1, 2 and 4 seconds with the default retryDelay of 1000
durability.enabledfalseKeep pending deliveries in SQLite across restarts

By default the queue lives in memory, so deliveries still waiting when the process stops are lost, and a delivery that fails every retry is logged and dropped. Turn on durability when you can't lose events:

durability: { enabled: true, path: '.openwa/webhook-deliveries.sqlite', replayLimit: 1000 },

open-wa then replays pending deliveries after a restart, sends each with an Idempotency-Key header, and marks deliveries that exhaust their retries as dead letters in the same file. Duplicates can still arrive if your receiver stored an event but its response was lost, so always store the key before you return 2xx, as the receiver above does.

Troubleshooting

ProblemFix
The receiver gets nothingCheck that @open-wa/integration-webhook is in plugins and the event name is in events. The --webhook flag alone does nothing.
The log shows connection errorsStart the receiver before open-wa, and check that the open-wa host can reach the url.
The receiver returns 401Use the same WEBHOOK_SECRET for open-wa and the receiver.
The same event arrives twiceReturn 2xx quickly and ignore keys you've already stored.
Events are lost after a restartSet durability.enabled: true.

For a full bot built on webhooks, see the Python bot.

Configuration types

Prop

Type

Prop

Type

Was this helpful?

Your answer includes the page path and docs version.

On this page