Receive Real-Time Delivery Events — Zexa Webhooks API

curl -X POST https://api.zexa.ao/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/zexa",
    "events": ["message.delivered", "message.failed", "message.optout"]
  }'

import requests

response = requests.post(
    "https://api.zexa.ao/v1/webhooks",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://yourapp.com/webhooks/zexa",
        "events": ["message.delivered", "message.failed", "message.optout"],
    },
)

print(response.json())

import hashlib
import hmac

def verify_zexa_signature(raw_body: bytes, secret: str, header_signature: str) -> bool:
    """
    Verify the HMAC-SHA256 signature on an incoming Zexa webhook request.

    Args:
        raw_body: The raw, undecoded request body bytes.
        secret: Your webhook secret from the Zexa dashboard.
        header_signature: The value of the X-Zexa-Signature header.

    Returns:
        True if the signature is valid, False otherwise.
    """
    expected = hmac.new(
        key=secret.encode("utf-8"),
        msg=raw_body,
        digestmod=hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, header_signature)


# Example usage in a Flask handler
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "your_webhook_secret_here"

@app.route("/webhooks/zexa", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Zexa-Signature", "")

    if not verify_zexa_signature(request.get_data(), WEBHOOK_SECRET, signature):
        abort(403)

    event = request.get_json()
    # Queue the event for async processing here
    return "", 200

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

const app = express();
const WEBHOOK_SECRET = "your_webhook_secret_here";

app.post(
  "/webhooks/zexa",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-zexa-signature"] || "";
    const expected = crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
      return res.status(403).send("Invalid signature");
    }

    const event = JSON.parse(req.body);
    // Queue the event for async processing here
    res.sendStatus(200);
  }
);