WhatsApp Webhooks

​

Inbound (Meta → Vobiz)

https://api.vobiz.ai/api/v1/webhooks/whatsapp

​

Outbound (Vobiz → your server)

​

How it works

1. Register a subscription - POST /api/v1/messaging/webhooks with your url and a secret.
2. An event occurs - a customer messages you, a message you sent changes delivery status, or a call event happens.
3. Vobiz POSTs to your url - with the common envelope as the JSON body, an X-Webhook-Signature header, and an X-Webhook-Event header.
4. Your server verifies and responds - validate the signature, then return 200 quickly and process asynchronously.

​

Base URL

https://api.vobiz.ai/api/v1/messaging

​

Authentication

X-Auth-ID: MA_XXXXXXXX
X-Auth-Token: <token>

​

Event Types

• message.inbound - an end customer sent a message to your WhatsApp number.
• message.status - a delivery-status update for a message you sent. The status field is one of sent, delivered, read, or failed.
• call.<event> - a WhatsApp Business Calling lifecycle event, e.g. call.connect, call.status_change, call.terminate.

​

Security

​

Verifying the signature

1. Read the raw request body (do not re-serialize the parsed JSON - HMAC is over the exact bytes).
2. Compute HMAC-SHA256(raw_body, your_secret) and hex-encode it.
3. Constant-time compare against the X-Webhook-Signature header. Reject on mismatch.

import hmac, hashlib
from flask import Flask, request, abort

WEBHOOK_SECRET = "your-shared-secret"  # the secret you registered

app = Flask(__name__)

@app.post("/webhooks/whatsapp")
def receive():
    raw = request.get_data()  # exact bytes
    expected = hmac.new(WEBHOOK_SECRET.encode(), raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Webhook-Signature", "")
    if not hmac.compare_digest(expected, received):
        abort(401)

    event = request.headers.get("X-Webhook-Event")  # e.g. "message.inbound"
    payload = request.get_json()
    # ... handle event ...
    return "", 200

const crypto = require("crypto");
const express = require("express");

const WEBHOOK_SECRET = "your-shared-secret";
const app = express();

// capture the raw body for HMAC verification
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/whatsapp", (req, res) => {
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body) // raw Buffer
    .digest("hex");
  const received = req.get("X-Webhook-Signature") || "";

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const event = req.get("X-Webhook-Event"); // e.g. "message.status"
  const payload = JSON.parse(req.body.toString());
  // ... handle event ...
  res.sendStatus(200);
});

​

Additional notes

• HTTPS only - your url must be an HTTPS endpoint.
• Replay protection (inbound leg) - on the Meta → Vobiz leg, Vobiz validates X-Hub-Signature-256 and enforces a replay window, rejecting stale or future-dated payloads.
• Deduplicate on the envelope’s event_id - deliveries can be retried.

​

Best Practices

• Respond quickly - return 200 within a few seconds. Do heavy work asynchronously in a queue so you don’t hit the delivery timeout.
• Verify every request - never trust a request to your webhook URL without a valid X-Webhook-Signature.
• Deduplicate - use event_id to ignore repeated deliveries.
• Route on X-Webhook-Event - switch on the header (which equals event_type) before parsing.

​

Real-time UI stream (optional)

wss://api.vobiz.ai/api/v1/messaging/ws

​

Next Steps

• Webhook Event Reference →
• Webhooks API →
• Managing Conversations →
• Send Messages via API →