Webhooks
Add an HTTPS endpoint in Settings → Developer → Webhooks and choose events: message.received, message.sent, message.status. We copy the signing secret to you once.
Payload
{
"id": "evt_7f3c…",
"event": "message.received",
"created_at": "2026-11-20T10:15:00Z",
"data": {
"message": {
"id": "…",
"direction": "in",
"type": "text",
"body": "Is the blue kurta in stock?",
"status": "received"
},
"contact": {
"wa_id": "919812345678",
"name": "Asha"
}
}
}
Headers
X-Apimaster-Event-Id | Unique per event — use it to ignore duplicates. |
X-Apimaster-Timestamp | Unix seconds when signed. |
X-Apimaster-Signature | sha256= + hex HMAC-SHA256(secret, timestamp + "." + rawBody). |
Verify — Node.js
import crypto from 'node:crypto';
import express from 'express';
const app = express();
// Keep the raw body: the signature covers the exact bytes we sent.
app.post('/apimaster-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('x-apimaster-timestamp') ?? '';
const sig = req.get('x-apimaster-signature') ?? '';
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.APIMASTER_WEBHOOK_SECRET)
.update(ts + '.' + req.body.toString('utf8')).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
if (!fresh || sig.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
return res.status(401).end();
}
const event = JSON.parse(req.body.toString('utf8'));
// Process idempotently: the same event id can arrive more than once.
console.log(event.id, event.event);
res.status(200).end();
});
app.listen(3000);Verify — Python
import hmac, hashlib, os, time, json
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["APIMASTER_WEBHOOK_SECRET"].encode()
@app.post("/apimaster-webhook")
def hook():
ts = request.headers.get("X-Apimaster-Timestamp", "")
sig = request.headers.get("X-Apimaster-Signature", "")
raw = request.get_data() # raw bytes, before any JSON parsing
expected = "sha256=" + hmac.new(SECRET, ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
if abs(time.time() - float(ts or 0)) > 300 or not hmac.compare_digest(sig, expected):
abort(401)
event = json.loads(raw)
print(event["id"], event["event"])
return "", 200Verify — PHP
<?php
$secret = getenv('APIMASTER_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_APIMASTER_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_APIMASTER_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (abs(time() - (int)$ts) > 300 || !hash_equals($expected, $sig)) {
http_response_code(401); exit;
}
$event = json_decode($raw, true);
error_log($event['id'] . ' ' . $event['event']);
http_response_code(200);
Delivery rules
- Reply with any 2xx within 10 seconds; do heavy work afterwards.
- Non-2xx or timeouts are retried with backoff, up to 8 attempts, then marked as given up (visible in the app).
- We never follow redirects and only deliver to public HTTPS addresses.
- Order is best-effort — use
created_atand the message status, not arrival order.