Webhooks

Registering an endpoint

KEY=$(openssl rand -base64 32)

curl -X POST https://api.wpai.co.in/api/org/webhooks \
  -H "X-API-Key: $WPAI_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"https://example.com/hooks/wpai\",
    \"secret\": \"$KEY\",
    \"events\": [\"message.inbound\", \"message.status\", \"template.status\"]
  }"

• secret is optional — bring your own, or we mint one. It must be 32 random bytes, base64 encoded, in either the standard or URL-safe alphabet.
• events is optional. Omitted, the webhook subscribes to everything available at that moment.
• The secret is returned once, in the create response, and never shown again.

Every event

What a delivery looks like

A POST with Content-Type: application/json and two headers of ours. The body is always the same three keys — the event name, when it happened, and the payload.

POST /hooks/wpai HTTP/1.1
Content-Type: application/json
X-WpAi-Event: message.inbound
X-WpAi-Signature: sha256=6f1c9d…

{
  "event": "message.inbound",
  "timestamp": "2026-08-26T09:14:22.104Z",
  "data": {
    "from": "919876543210",
    "name": "Priya Sharma",
    "type": "text",
    "text": "Is the shop open today?",
    "messageId": "wamid.HBg…"
  }
}

Respond with any 2xx. We do not read your response body. Anything else, or a timeout after ten seconds, counts as a failure.

Verifying a delivery

X-WpAi-Signature is sha256= followed by a hex HMAC-SHA256 of the raw request body, keyed with your signing secret.

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body, not express.json() — the signature covers the exact bytes we sent.
app.post('/hooks/wpai', express.raw({ type: 'application/json' }), (req, res) => {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', process.env.WPAI_WEBHOOK_SECRET).update(req.body).digest('hex');

  const given = req.get('X-WpAi-Signature') ?? '';
  const ok =
    given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));

  if (!ok) return res.sendStatus(401);

  const { event, data } = JSON.parse(req.body.toString('utf8'));
  // Acknowledge first, work afterwards — we time out after 10 seconds.
  res.sendStatus(200);
  void handle(event, data);
});

Retries and failures

• Three attempts per event, with roughly 5 and 10 second gaps. We stop after the third.
• Ten second timeout per attempt.
• Deliveries are not ordered and not deduplicated. A retry after your handler already succeeded is possible, so make handlers idempotent on messageId.
• GET /api/org/webhooks reports lastDeliveryStatus and failureCount.

Payload reference

Every field of every event's data object.