Webhook

Receive real-time notifications when messages arrive on your WhatsApp account.

How It Works

Configure your webhook URL in the device settings. When a message is received, the engine sends a POST request to your URL with the message payload.

Example Handler

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const { event, node, message } = req.body;

  console.log(`[${event}] from ${node.phone}`);
  console.log(`Message: ${message.content.text}`);

  // ** Return 2xx to acknowledge
  res.status(200).json({ received: true });
});

app.listen(3000);

Webhook Payload

When a message is received, the engine sends a POST request to your webhook URL.

eventstring

Event type. Currently: MESSAGE_RECEIVED.

eventAtstring

ISO 8601 timestamp of when the webhook was triggered.

nodeobject

The WhatsApp node that received the message. Contains guid and phone.

messageobject

The received message payload. Contains id, from, type, content, messagedAt, isGroup.

message.fromobject

Sender info with jid, name, and phone.

message.isGroupboolean

Whether the message came from a group. If true, groupJid is included.

{
  "event": "MESSAGE_RECEIVED",
  "eventAt": "2026-02-01T10:30:45.123Z",
  "node": {
    "guid": "abc-123-def",
    "phone": "+6281234567890"
  },
  "message": {
    "id": "3EB0ABC123DEF456",
    "from": {
      "jid": "[email protected]",
      "name": "John Doe",
      "phone": "+6289876543210"
    },
    "type": "TEXT",
    "content": {
      "text": "Hello, how are you?"
    },
    "messagedAt": 1706780445,
    "isGroup": false
  }
}

Message Types

The message.type field determines the structure of message.content.

Type	Content Fields
TEXT	text
IMAGE	caption, mimetype
VIDEO	caption, mimetype
AUDIO	mimetype
DOCUMENT	fileName, mimetype
STICKER	mimetype
REACTION	emoji, reactedMessageId
OTHER	(varies)

Content by Type

// TEXT
{ "text": "Hello!" }

// IMAGE
{ "caption": "Photo", "mimetype": "image/jpeg" }

// VIDEO
{ "caption": "Video", "mimetype": "video/mp4" }

// AUDIO
{ "mimetype": "audio/ogg" }

// DOCUMENT
{ "fileName": "report.pdf", "mimetype": "application/pdf" }

// STICKER
{ "mimetype": "image/webp" }

// REACTION
{ "emoji": "👍", "reactedMessageId": "3EB0..." }

Retry Mechanism

Failed webhooks are automatically retried with increasing delays.

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

After 4 failed attempts, the webhook is marked as permanently failed for that message.

Expected response from your server

{
  "received": true
}