Integrations

Webhooks

Receive real-time HTTP notifications when events happen in MotherBot — messages, campaigns, contact changes, and more.

How Webhooks Work

When an event occurs (a message is received, a campaign completes, etc.), MotherBot sends an HTTP POST request to your configured endpoint with a JSON payload. Your server should respond with a 200 OK within 10 seconds.

Note

If your endpoint returns a non-2xx status or times out, MotherBot retries with exponential backoff: 10s → 30s → 2min → 10min → 1hr. After 5 failures the event is marked as dropped.

Setting Up a Webhook

Create an endpoint on your server

Your endpoint must be publicly accessible over HTTPS. For local development, use a tunnel like ngrok:

ngrok http 3000
# Copy the https:// forwarding URL

Go to Dashboard → Webhooks → Add Endpoint. Enter your URL, optionally add a description, and select which events to subscribe to.

Copy the signing secret

MotherBot generates a Signing Secret for each webhook. Store it securely — you'll use it to verify that requests are from MotherBot.

Verify the signature

Every webhook request includes an X-MotherBot-Signature header:

const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)        // raw request body (string)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

// In your Express handler:
app.post("/webhook", (req, res) => {
  const sig = req.headers["x-motherbot-signature"];
  if (!verifyWebhook(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  const event = req.body;
  // handle event...
  res.sendStatus(200);
});

Event Types

Event	When it fires
message.received	A contact sends your number a message.
message.delivered	A sent message reaches the recipient's device.
message.read	Recipient opens a message you sent.
message.failed	A message permanently failed to deliver.
campaign.started	A campaign begins sending.
campaign.completed	All messages in a campaign have been processed.
contact.created	A new contact is created (import, API, or first message).
contact.updated	A contact's fields are changed.
contact.opted_out	A contact sends STOP or an opt-out keyword.
chatbot.completed	A chatbot sequence ran to completion.
flow.submitted	A contact submits a WhatsApp Flow.
conversation.resolved	An agent marks a conversation as Resolved.

Payload Format

All events share the same envelope structure:

{
  "event": "message.received",
  "timestamp": "2026-06-14T09:32:11.000Z",
  "organizationId": "org_abc123",
  "data": {
    // event-specific payload
  }
}

Example message.received payload:

{
  "event": "message.received",
  "timestamp": "2026-06-14T09:32:11.000Z",
  "organizationId": "org_abc123",
  "data": {
    "messageId": "wamid.abc...",
    "from": "+12125551234",
    "contactId": "cid_xyz",
    "contactName": "John Smith",
    "type": "text",
    "text": "Hello, I need help",
    "timestamp": "2026-06-14T09:32:10.000Z"
  }
}

Testing Webhooks

In Webhooks → [your endpoint] → Test, click Send Test Event to send a dummy payload.
The delivery log shows every request: timestamp, response code, duration, and body.
Filter the log by event type or date to debug specific issues.
Use the Resend button on any failed delivery to retry immediately.

Analytics & Reports

API Reference