Webhooks

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Armage-Webhooks/1 (+https://arm-age.com/developers/webhooks)
webhook-id: 3f6d2c1e-8a4b-4f0e-9d7a-2b5c6e1f0a93
webhook-timestamp: 1791450000
webhook-signature: v1,<base64 HMAC-SHA256 of "{webhook-id}.{webhook-timestamp}.{body}">

{
  "id": "3f6d2c1e-8a4b-4f0e-9d7a-2b5c6e1f0a93",
  "object": "event",
  "type": "story.published",
  "created_at": "2026-10-08T09:00:00.000Z",
  "data": {
    "story_id": "0b8e…",
    "story": {
      "object": "story",
      "id": "0b8e…",
      "type": "insight",
      "slug": "what-changes-in-2027",
      "status": "published",
      "title": "What changes in 2027",
      "summary": "…",
      "version": 2,
      "topics": ["healthcare"],
      "published_at": "2026-10-08T09:00:00.000Z",
      "created_at": "2026-10-01T14:12:00.000Z",
      "updated_at": "2026-10-08T09:00:00.000Z"
    }
  }
}

// Node 20+, Deno, Bun or Cloudflare Workers (WebCrypto). No dependency.
export async function verifyArmageWebhook(
  secret: string, // whsec_…, shown once when you added the endpoint
  headers: Headers,
  rawBody: string, // the body exactly as received, before JSON.parse
): Promise<boolean> {
  const id = headers.get('webhook-id');
  const timestamp = headers.get('webhook-timestamp');
  const signatures = headers.get('webhook-signature');
  if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const raw = Uint8Array.from(atob(secret.slice('whsec_'.length)), (c) => c.charCodeAt(0));
  const key = await crypto.subtle.importKey(
    'raw', raw, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'],
  );
  const mac = await crypto.subtle.sign(
    'HMAC', key, new TextEncoder().encode(`${id}.${timestamp}.${rawBody}`),
  );
  const expected = `v1,${btoa(String.fromCharCode(...new Uint8Array(mac)))}`;
  return signatures.split(' ').some((candidate) => {
    if (candidate.length !== expected.length) return false;
    let diff = 0;
    for (let i = 0; i < expected.length; i++) diff |= candidate.charCodeAt(i) ^ expected.charCodeAt(i);
    return diff === 0;
  });
}

# Python 3.9+, standard library only.
import base64, hashlib, hmac, time

def verify_armage_webhook(secret: str, headers, raw_body: bytes) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature") or ""
    if not msg_id or not timestamp or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    digest = hmac.new(key, signed, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()
    return any(hmac.compare_digest(expected, s) for s in signatures.split(" "))

<?php
// PHP 7.4+. In a WordPress REST route: $request->get_header('webhook-id'),
// $request->get_body() for the raw body.
function armage_verify_webhook(string $secret, string $id, string $timestamp,
                               string $signatures, string $raw_body): bool {
    if ($id === '' || !ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
        return false;
    }
    $key = base64_decode(substr($secret, strlen('whsec_')), true);
    if ($key === false) {
        return false;
    }
    $expected = 'v1,' . base64_encode(hash_hmac('sha256', "$id.$timestamp.$raw_body", $key, true));
    foreach (explode(' ', $signatures) as $candidate) {
        if (hash_equals($expected, $candidate)) {
            return true;
        }
    }
    return false;
}