Webhooks

​

How a delivery works

1. The event is committed to our outbox as a WebhookDelivery with a stable UUID.
2. A worker POSTs the JSON body to your URL.
3. We record an attempt row with status code, duration, and response body.
4. On 5xx or network errors we retry up to 3 times with exponential backoff (10s, 30s, 90s).
5. After 20 consecutive failures the webhook is auto-disabled and you get a banner in the dashboard.

​

Headers

​

Verifying signatures

import crypto from "node:crypto";

app.post("/webhooks/wassist", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.header("x-wassist-signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const signedPayload = `${parts.t}.${req.body.toString("utf-8")}`;
  const expected = crypto
    .createHmac("sha256", process.env.WASSIST_WEBHOOK_SECRET!)
    .update(signedPayload)
    .digest("hex");

  const ok = crypto.timingSafeEqual(
    Buffer.from(parts.v1, "hex"),
    Buffer.from(expected, "hex"),
  );
  if (!ok) return res.status(400).send("bad signature");

  // Replay protection: reject events more than 5 minutes old.
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) {
    return res.status(400).send("stale");
  }

  // Idempotency: drop duplicate deliveries.
  const deliveryId = req.header("x-wassist-delivery")!;
  if (await alreadyProcessed(deliveryId)) return res.status(200).send("ok");

  await handle(JSON.parse(req.body.toString("utf-8")));
  await markProcessed(deliveryId);
  res.status(200).send("ok");
});

import hmac, hashlib, time

def verify(request, secret: str) -> bool:
    header = request.headers.get("X-Wassist-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, received = parts.get("t", ""), parts.get("v1", "")
    signed = f"{ts}.".encode() + request.body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(received, expected):
        return False
    return abs(time.time() - int(ts)) <= 300

func verify(r *http.Request, secret string) bool {
    body, _ := io.ReadAll(r.Body)
    header := r.Header.Get("X-Wassist-Signature")
    var ts, sig string
    for _, p := range strings.Split(header, ",") {
        kv := strings.SplitN(p, "=", 2)
        if len(kv) == 2 {
            if kv[0] == "t" { ts = kv[1] }
            if kv[0] == "v1" { sig = kv[1] }
        }
    }
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(ts + "."))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))
    if !hmac.Equal([]byte(sig), []byte(expected)) {
        return false
    }
    epoch, _ := strconv.ParseInt(ts, 10, 64)
    return time.Now().Unix()-epoch <= 300
}

​

Event catalog

​

message.received

{
  "event": "message.received",
  "timestamp": "2026-06-23T16:48:00.000Z",
  "phoneNumber": "+447700900100",
  "from": "+447700900200",
  "contact": { "name": "Alex", "phoneNumber": "+447700900200" },
  "message": {
    "id": "01HXYZ...",
    "waId": "wamid.HBgL...",
    "body": "Hey, can I add another item to my order?",
    "media": [],
    "buttons": [],
    "referral": null
  },
  "conversationId": "5a3f...e2",
  "latestReferral": null
}

​

Ad attribution (Click-to-WhatsApp)

"referral": {
  "messageId": "01HXYZ...",
  "sourceType": "ad",
  "sourceId": "120210000000000000",
  "sourceUrl": "https://fb.me/abc123",
  "headline": "Summer sale — 20% off",
  "body": "Chat with us to find your size",
  "mediaType": "image",
  "imageUrl": "https://scontent.xx.fbcdn.net/...",
  "videoUrl": null,
  "thumbnailUrl": null,
  "ctwaClid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a",
  "welcomeMessage": "Hi! How can we help?",
  "createdAt": "2026-06-23T16:48:00Z"
}

​

test.ping

​

Best practices

• Idempotency. Store the X-Wassist-Delivery ID and reject duplicates. We use the same ID across all retries.
• Respond fast. Send a 2xx within 10 seconds and do real work asynchronously. We treat slow responses as failures and retry.
• Replay protection. Reject events where X-Wassist-Timestamp is more than 5 minutes from now.
• Rotate secrets. From the dashboard, Rotate secret generates a new secret. The old one stops working immediately.
• Local development. Use the CLI: wassist listen tunnels real events to localhost without exposing a public URL.

​

Replaying deliveries

• Filter deliveries by status (all / failed / succeeded).
• Open a delivery to see request headers, response body, and the timeline of every retry attempt.
• Click Replay to send a fresh copy of the same payload (it gets a new X-Wassist-Delivery ID).