Webhooks

When a user sends a message to your WhatsApp number, or when the delivery status of an outbound message changes, the Connexease Gateway forwards that event to your server as an HTTP POST request. This page explains how to register your endpoint, what each event payload looks like, and how to handle retries and failure scenarios correctly.

How It Works

Meta sends a webhook to the Connexease Gateway.
The Gateway verifies the signature and forwards the event to your registered webhook URL.
Your server must return HTTP 200. Heavy processing must be done asynchronously.

Setup

Step 1 — Register Your Webhook URL

Dashboard → Settings → Webhooks → enter your URL and set a webhook secret.

Step 2 — Choose Your Events

Select the events your application should receive:

Event Name	Trigger
`messages`	A user sent a message to your WhatsApp number
`message_status`	Outbound message status changed (sent, delivered, failed)
`read`	A user read your outbound message
`message_template_status`	A template was approved, rejected, or paused
`account`	Account or phone number update

Step 3 — Prepare Your Endpoint

Your webhook endpoint must:

Be accessible over HTTPS with a valid SSL certificate
Return HTTP 200 within 5 seconds
Handle heavy operations asynchronously (background job, queue)

import express from 'express';
const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
  // 1. Verify the request comes from Connexease Gateway
  const auth = req.headers['authorization'];
  if (!auth || auth !== `Bearer ${WEBHOOK_SECRET}`) {
    return res.status(401).send('Unauthorized');
  }

  // 2. Acknowledge immediately — never delay this
  res.sendStatus(200);

  // 3. Process asynchronously
  setImmediate(() => processWebhook(req.body));
});

function processWebhook(body) {
  const changes = body?.entry?.[0]?.changes ?? [];
  for (const change of changes) {
    const value = change.value;

    for (const msg of value?.messages ?? []) {
      handleIncomingMessage(msg, value.contacts?.[0], value.metadata);
    }

    for (const status of value?.statuses ?? []) {
      handleStatusUpdate(status);
    }
  }
}

function handleIncomingMessage(msg, contact, metadata) {
  console.log(`[${msg.type.toUpperCase()}] from ${msg.from} (${contact?.profile?.name})`);
  // Access msg.text / msg.image / msg.audio / msg.document / msg.interactive / msg.location
}

function handleStatusUpdate(status) {
  console.log(`${status.id} → ${status.status}`);
  if (status.status === 'failed') {
    console.error('Delivery failed:', status.errors);
  }
}

app.listen(3000);

Retry Policy

If your server returns a connection error or HTTP 5xx, the Dispatcher retries:

Attempt	Wait before retry
1st attempt	Immediate
2nd attempt	After 1 second
3rd attempt	After 2 seconds

After 3 failed attempts, the event is dropped and logged to ClickHouse with ProcessingStatus: ERROR.

HTTP 4xx responses are treated as permanent failures and are not retried. If you return 401 Unauthorized (e.g. wrong secret), the event is lost.

Incoming Message Payloads

Text Message

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID_123456",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "905321234567",
          "phone_number_id": "PHONE_NUMBER_ID_123"
        },
        "contacts": [{
          "profile": { "name": "John Smith" },
          "wa_id": "905399876543"
        }],
        "messages": [{
          "from": "905399876543",
          "id": "wamid.HBgNOTA1Mzk5ODc2NTQzFQIAERgSM0Y3RDg5NjREOUNBMkFFNEE3AA==",
          "timestamp": "1711900000",
          "type": "text",
          "text": { "body": "Hello, I'd like to know the status of my order." }
        }]
      }
    }]
  }]
}

Field Reference:

Field	Type	Description
`entry[0].id`	string	WhatsApp Business Account (WABA) ID
`value.metadata.phone_number_id`	string	Meta ID of the phone number that received the message. Critical for routing.
`value.metadata.display_phone_number`	string	Human-readable phone number
`value.contacts[0].wa_id`	string	Sender’s WhatsApp ID (phone number)
`value.contacts[0].profile.name`	string	Sender’s WhatsApp display name
`value.messages[0].from`	string	Sender’s phone number
`value.messages[0].id`	string	Unique ID of the incoming message
`value.messages[0].timestamp`	string	Unix timestamp (in seconds)
`value.messages[0].type`	string	`text`, `image`, `audio`, `document`, `interactive`, `location`
`value.messages[0].text.body`	string	Message content (for `type: "text"`)

Image Message

{
  "messages": [{
    "from": "905399876543",
    "id": "wamid.xxx",
    "timestamp": "1711900050",
    "type": "image",
    "image": {
      "caption": "Product photo",
      "mime_type": "image/jpeg",
      "sha256": "abc123...",
      "id": "MEDIA_ID_789"
    }
  }]
}

Field	Description
`image.id`	Media ID. Use the `/media/{id}` endpoint to download the content.
`image.mime_type`	File type (`image/jpeg`, `image/png`)
`image.sha256`	Hash for file integrity verification
`image.caption`	Caption written by the user (optional)

Audio Message

{
  "messages": [{
    "from": "905399876543",
    "id": "wamid.xxx",
    "timestamp": "1711900100",
    "type": "audio",
    "audio": {
      "mime_type": "audio/ogg; codecs=opus",
      "sha256": "def456...",
      "id": "MEDIA_ID_456",
      "voice": true
    }
  }]
}

Field	Description
`audio.id`	Media ID for downloading the audio file
`audio.voice`	`true` = user sent a voice note
`audio.mime_type`	`audio/ogg; codecs=opus`, `audio/mp4`, etc.

Document Message

{
  "messages": [{
    "from": "905399876543",
    "id": "wamid.xxx",
    "timestamp": "1711900150",
    "type": "document",
    "document": {
      "caption": "Invoice",
      "filename": "invoice_march_2025.pdf",
      "mime_type": "application/pdf",
      "sha256": "ghi789...",
      "id": "MEDIA_ID_321"
    }
  }]
}

Interactive — Button Reply

Received when a user taps one of the buttons you sent:

{
  "messages": [{
    "from": "905399876543",
    "id": "wamid.xxx",
    "timestamp": "1711900200",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "home_delivery",
        "title": "Home Delivery"
      }
    }
  }]
}

Field	Description
`interactive.button_reply.id`	The `reply.id` you set when sending the button message
`interactive.button_reply.title`	The button label shown to the user

Interactive — List Reply

Received when a user selects an item from a list you sent:

{
  "messages": [{
    "from": "905399876543",
    "id": "wamid.xxx",
    "timestamp": "1711900250",
    "type": "interactive",
    "interactive": {
      "type": "list_reply",
      "list_reply": {
        "id": "track_order",
        "title": "Track Order",
        "description": "Find out where your order is"
      }
    }
  }]
}

Location Message

{
  "messages": [{
    "from": "905399876543",
    "id": "wamid.xxx",
    "timestamp": "1711900300",
    "type": "location",
    "location": {
      "latitude": 41.0082376,
      "longitude": 28.9783589,
      "name": "Taksim Square",
      "address": "Taksim, Istanbul"
    }
  }]
}

Status Update Payloads

Sent

{
  "statuses": [{
    "id": "wamid.HBgNOTA1Mzk5ODc2NTQzFQIAERgSM0Y3RDg5NjREOUNBMkFFNEE3AA==",
    "status": "sent",
    "timestamp": "1711900400",
    "recipient_id": "905399876543",
    "conversation": {
      "id": "CONV_ID_111",
      "origin": { "type": "utility" }
    },
    "pricing": {
      "billable": true,
      "pricing_model": "CBP",
      "category": "utility"
    }
  }]
}

Delivered

The Gateway automatically deducts the Meta fee when status: "delivered" and pricing.billable: true.

{
  "statuses": [{
    "id": "wamid.HBgNOTA1Mzk5ODc2NTQzFQIAERgSM0Y3RDg5NjREOUNBMkFFNEE3AA==",
    "status": "delivered",
    "timestamp": "1711900450",
    "recipient_id": "905399876543",
    "conversation": {
      "id": "CONV_ID_111",
      "origin": { "type": "utility" }
    },
    "pricing": {
      "billable": true,
      "pricing_model": "CBP",
      "category": "utility"
    }
  }]
}

Status Update Field Reference:

Field	Type	Description
`statuses[0].id`	string	The `wamid` of the message you sent — match with the stored ID
`statuses[0].status`	string	`sent`, `delivered`, `read`, `failed`
`statuses[0].timestamp`	string	Unix timestamp of the status change
`statuses[0].recipient_id`	string	Recipient’s phone number
`statuses[0].conversation.id`	string	Meta conversation ID
`statuses[0].conversation.origin.type`	string	Conversation category: `marketing`, `utility`, `authentication`, `service`
`statuses[0].pricing.billable`	bool	`true` = Meta fee will be deducted, `false` = free tier
`statuses[0].pricing.category`	string	Billing category

Read

{
  "statuses": [{
    "id": "wamid.HBgNOTA1Mzk5ODc2NTQzFQIAERgSM0Y3RDg5NjREOUNBMkFFNEE3AA==",
    "status": "read",
    "timestamp": "1711900500",
    "recipient_id": "905399876543"
  }]
}

Failed

{
  "statuses": [{
    "id": "wamid.xxx",
    "status": "failed",
    "timestamp": "1711900550",
    "recipient_id": "905399876543",
    "errors": [{
      "code": 131047,
      "title": "Re-engagement message",
      "message": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
      "error_data": {
        "details": "The recipient phone is not reachable or has not opted in."
      }
    }]
  }]
}

Field	Description
`errors[0].code`	Meta error code (full list: Meta Docs)
`errors[0].title`	Short error title
`errors[0].message`	Detailed description

System Event Payloads

Template Status Update

{
  "entry": [{
    "id": "WABA_ID_123456",
    "changes": [{
      "field": "message_template_status_update",
      "value": {
        "event": "APPROVED",
        "message_template_id": 1234567890,
        "message_template_name": "order_confirmation",
        "message_template_language": "en_US",
        "reason": null
      }
    }]
  }]
}

`event` Value	Description
`APPROVED`	Template is ready to use
`REJECTED`	Template was rejected — check the `reason` field
`PENDING_DELETION`	Template is scheduled for deletion
`FLAGGED`	Template was flagged by Meta
`PAUSED`	Paused due to low quality score

Account Update

{
  "entry": [{
    "id": "WABA_ID_123456",
    "changes": [{
      "field": "account_update",
      "value": {
        "phone_number": "905321234567",
        "event": "ACCOUNT_UPDATE",
        "ban_info": {
          "waba_ban_state": "SCHEDULE_FOR_DISABLE",
          "waba_ban_date": "2025-05-01"
        }
      }
    }]
  }]
}

Key Notes

No delivery order guarantee. sent and delivered events may not arrive in order. Sort by statuses[0].timestamp.

Idempotency: Network issues or the retry mechanism may deliver the same wamid more than once. Make your processing logic idempotent (safe to run multiple times for the same ID).

Quick test: Messages sent with is_fake=true do not generate delivered webhooks. Use a real number or Meta’s test phone numbers to test the full webhook flow.

Checklist

Is your HTTPS endpoint publicly accessible?

Must have a valid SSL certificate and be reachable from the internet.

Are you returning HTTP 200 within 5 seconds?

Move DB writes, API calls, and emails to a background job.

Are you validating the Authorization header?

Without the Bearer WEBHOOK_SECRET check, you’re open to forged events.

Is your processing idempotent?

Ensure the same wamid cannot trigger duplicate side effects.

Have you subscribed to the right events?

At minimum, messages and message_status should be active in the Dashboard.

Sandbox

Messaging

Reference

Webhooks

How It Works

Setup

Step 1 — Register Your Webhook URL

Step 2 — Choose Your Events

Step 3 — Prepare Your Endpoint

Retry Policy

Incoming Message Payloads

Text Message

Image Message

Audio Message

Document Message

Interactive — Button Reply

Interactive — List Reply

Location Message

Status Update Payloads

Sent

Delivered

Read

Failed

System Event Payloads

Template Status Update

Account Update

Key Notes

Checklist

Sandbox

Messaging

Webhooks

Reference

Documentation Index

​How It Works

​Setup

​Step 1 — Register Your Webhook URL

​Step 2 — Choose Your Events

​Step 3 — Prepare Your Endpoint

​Retry Policy

​Incoming Message Payloads

​Text Message

​Image Message

​Audio Message

​Document Message

​Interactive — Button Reply

​Interactive — List Reply

​Location Message

​Status Update Payloads

​Sent

​Delivered

​Read

​Failed

​System Event Payloads

​Template Status Update

​Account Update

​Key Notes

​Checklist

How It Works

Setup

Step 1 — Register Your Webhook URL

Step 2 — Choose Your Events

Step 3 — Prepare Your Endpoint

Retry Policy

Incoming Message Payloads

Text Message

Image Message

Audio Message

Document Message

Interactive — Button Reply

Interactive — List Reply

Location Message

Status Update Payloads

Sent

Delivered

Read

Failed

System Event Payloads

Template Status Update

Account Update

Key Notes

Checklist