Skip to main content
The Connexease Gateway forwards incoming events from WhatsApp directly to your server via HTTP POST requests. Instead of continuously polling for new messages, your application can listen for these webhooks to respond to customers instantly.

​
Webhook Requirements & Best Practices

To ensure reliable delivery of events without latency, your webhook endpoint must meet the following criteria:
  1. HTTPS Enabled: Your webhook endpoint must be publicly accessible and secured with a valid SSL/TLS certificate (HTTPS).
  2. Fast 200 OK Response: You must return an HTTP 200 OK response as quickly as possible upon receiving the webhook. If your application requires heavy processing or database operations, we strongly recommend pushing the event to a background queue and returning 200 OK immediately to prevent timeouts.
  3. Security: Configure a Custom Webhook Secret in your Connexease dashboard. Our gateway will include Authorization: Bearer <your_secret> in every webhook request it forwards to you.

​
Supported Event Types

When configuring your webhook URL, you can subscribe to specific event types:
  • message: Triggered when a customer sends a new message to your WhatsApp number.
  • status: Triggered when the delivery status of an outbound message changes (e.g., sent, delivered, read, failed).
  • template: Triggered when the approval status of a WhatsApp message template changes.
  • account: Triggered for WhatsApp Business Account updates.

​
Payload Examples

Because the Connexease Gateway acts as a transparent proxy, the payloads you receive are identical to the official Meta WhatsApp Cloud API structures. This ensures full compatibility with existing WhatsApp libraries.

​
1. Incoming Message Payload

Triggered when a user sends a text, image, document, or interactive message. 
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "773308328526742",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "12345678900",
              "phone_number_id": "973255022542907"
            },
            "contacts": [
              {
                "profile": { "name": "John Doe" },
                "wa_id": "12345678900"
              }
            ],
            "messages": [
              {
                "from": "12345678900",
                "id": "wamid.HBgMOTA1Mzk4...",
                "timestamp": "1772173497",
                "type": "text",
                "text": { "body": "Hello, I need support." }
              }
            ]
          }
        }
      ]
    }
  ]
}

​
Integration Boilerplate (Node.js)

Here is a quick example of how to handle these incoming webhooks securely. 
const express = require('express');
const app = express();
app.use(express.json());

const MY_WEBHOOK_SECRET = "my_super_secret_token"; 

app.post('/webhook', (req, res) => {
    // 1. Authenticate the request
    const authHeader = req.headers['authorization'];
    if (authHeader !== `Bearer ${MY_WEBHOOK_SECRET}`) {
        return res.status(401).send("Unauthorized");
    }

    const body = req.body;

    // 2. Process WhatsApp Events
    if (body.object === 'whatsapp_business_account') {
        const changes = body.entry?.[0]?.changes?.[0]?.value;

        if (!changes) return res.sendStatus(200);

        if (changes.messages) {
            const msg = changes.messages[0];
            console.log(`[NEW MESSAGE] From ${msg.from}:`, msg.text?.body);
        }
        
        if (changes.statuses) {
            const status = changes.statuses[0];
            console.log(`[STATUS UPDATE] Message ${status.id} is now '${status.status}'`);
        }

        // 3. Always return 200 OK immediately
        res.sendStatus(200); 
    } else {
        res.sendStatus(404);
    }
});

app.listen(3000, () => console.log('Webhook server is listening on port 3000'));