Message webhooks

Whatsable can POST a JSON payload to your endpoint each time a WhatsApp message arrives on your number or is sent from it. That includes messages your team types by hand in the WhatsApp Business app on the phone. Use it to start a Make, Zapier or n8n automation, update a CRM, attribute ad leads, or keep a copy of your conversations.

This page is the reference for that payload. To add an endpoint, see outgoing webhooks.

Set up an endpointCopy Anchor Link

Your endpoint must accept POST requests with a JSON body over public HTTPS, and answer with a 2xx status quickly. Whatsable retries a failed delivery a few times. When an endpoint keeps answering "not found", Whatsable stops sending to it and the webhook shows Disabled: endpoint not found. Fix the endpoint, then select Enable.

Webhook payloadCopy Anchor Link

Every delivery is one JSON object. Which fields it holds depends on the direction of the message.

Incoming messageCopy Anchor Link

A customer wrote to your number. This example comes from a Your own server endpoint.

{
  "last_messages": "[{\"type\":\"user\",\"content\":\"Can you tell me more about the premium plan?\",\"timestamp\":\"2026-10-20T14:05:12.000Z\",\"content_type\":\"text\"},{\"type\":\"bot\",\"content\":\"Hi Sarah, how can we help?\",\"timestamp\":\"2026-10-20T14:01:40.000Z\",\"content_type\":\"text\"}]",
  "conversation_paragraph": "User (2:05:12 PM): Can you tell me more about the premium plan? ; Bot (2:01:40 PM): Hi Sarah, how can we help?",
  "phone_number": "14155552671",
  "recipient_name": "Sarah Johnson",
  "user_id": "9232fcef-a570-4a2c-b46b-6cab53aec304",
  "last_message_of_user": "Can you tell me more about the premium plan?",
  "last_message_of_bot": "Hi Sarah, how can we help?",
  "message_type": "text",
  "user_last_message_time": 1792505112,
  "bot_last_message_time": 1792504900,
  "attachment_url": "",
  "note": "Asked about pricing last week",
  "note_automation": "",
  "labels": "premium-inquiry, sales",
  "incoming_message": true,
  "is_scheduled": false
}

On a Make, Zapier or n8n endpoint, an incoming message has no incoming_message field at all. On a Your own server endpoint it is true. Treat a missing incoming_message as an incoming message.

Outgoing messageCopy Anchor Link

Your business sent a message. Only a Make, Zapier or n8n endpoint with Outgoing messages ticked receives these.

{
  "last_messages": "[{\"type\":\"bot\",\"content\":\"Yes, it includes three numbers.\",\"timestamp\":\"2026-10-20T14:07:02.000Z\",\"content_type\":\"text\"},{\"type\":\"user\",\"content\":\"Can you tell me more about the premium plan?\",\"timestamp\":\"2026-10-20T14:05:12.000Z\",\"content_type\":\"text\"}]",
  "conversation_paragraph": "Bot (2:07:02 PM): Yes, it includes three numbers. ; User (2:05:12 PM): Can you tell me more about the premium plan?",
  "phone_number": 14155552671,
  "recipient_name": "Sarah Johnson",
  "user_id": "9232fcef-a570-4a2c-b46b-6cab53aec304",
  "last_message_of_user": "Can you tell me more about the premium plan?",
  "last_message_of_bot": "Yes, it includes three numbers.",
  "message_type": "text",
  "user_last_message_time": 1792505112,
  "bot_last_message_time": 1792505222,
  "attachment_url": "",
  "note": "Asked about pricing last week",
  "note_automation": "",
  "labels": "premium-inquiry, sales",
  "incoming_message": false,
  "send_by": "WhatsApp App",
  "was_message_by_human": true
}

On an outgoing message, phone_number is a JSON number, not a string. When the last messages hold no message from the customer, last_message_of_user is left out.

Payload fieldsCopy Anchor Link

Combined messagesCopy Anchor Link

Customers often send several short messages in a row. On a Make, Zapier or n8n endpoint, turn on Combine quick messages: Whatsable waits until the customer has sent nothing new for the time you choose, then sends their messages as one request. That request has is_scheduled: true and a scheduled_messages field that holds the combined messages as one string. In it, labels is an array of names rather than a joined string, and phone_number is a number.

Pause when your team repliesCopy Anchor Link

Turn on Pause when your team replies to stop sending a chat's incoming messages for a while after a teammate replies, so your automation and your team don't both answer. The timer restarts every time your team replies. Replies from bots, broadcasts and the API don't pause it.

Click-to-WhatsApp adsCopy Anchor Link

When someone taps Send message on a Click-to-WhatsApp ad (Facebook, Instagram, or WhatsApp Status) and writes to your number, Meta attaches a referral object to that incoming message. Whatsable passes it on as a top-level referral field, to your own server and to your n8n, Make and Zapier automations.

Use it to see which ad, which creative and which platform produced the lead, then label the contact, route the chat, or send ctwa_clid to Meta's Conversions API.

{
  "message_type": "referral",
  "last_message_of_user": "I'd like more information",
  "referral": {
    "source_type": "ad",
    "source_id": "52540693396957",
    "source_url": "https://www.instagram.com/p/DZiVBz7gAF9/",
    "headline": "Spring sale",
    "body": "Get 20% off this week only.",
    "media_type": "image",
    "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/example.jpg",
    "ctwa_clid": "AfhN-JKvx8HeFTmfB-Tu11zktQRJ-MNdMV1mwvDNxHnpYrGl"
  }
}

Every referral field is described on Click-to-WhatsApp referral fields. WhatsApp Status ad placements may omit ctwa_clid. Organic posts use source_type: "post".

Verify the signatureCopy Anchor Link

When Sign requests was on, every request carries two headers. When it was off, these headers are absent.

To check a request, compute the HMAC-SHA256 of the timestamp, a dot and the raw request body (<timestamp>.<body>), with your signing secret as the key. Compare it with the hex value after sha256=. Reject a request whose signature does not match, or whose timestamp is too old.

const crypto = require('crypto');

function isFromWhatsable(rawBody, headers, secret) {
  const timestamp = headers['x-notifyer-timestamp'];
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const received = (headers['x-notifyer-signature-256'] || '').replace(/^sha256=/, '');
  if (received.length !== expected.length) return false;
  return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Keep the signing secret on your server. Never put it in client-side code or a public repository.

TroubleshootingCopy Anchor Link

FAQsCopy Anchor Link