Webhooks

POST /your/path HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: HocDoc-Webhooks/1.0
webhook-id: 6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f
webhook-timestamp: 1791533730
webhook-signature: v1,fvvg2fi8IO5CucqsptXcBbC5Kg+ia9x/PzREjEcYENI=

{
  "id": "e16a4b7c-3d82-4c95-a7f0-5b6c7d8e9f44",
  "type": "offer.accepted",
  "created_at": "2026-10-02T14:07:45.912Z",
  "api_version": "v1",
  "data": {
    "offer": {
      "id": "5d2c8a40-7b19-4e6f-a3d8-1c9e0f7b2a64",
      "title": "Brand identity package",
      "status": "accepted",
      "created_at": "2026-09-28T09:00:12.481Z",
      "updated_at": "2026-10-02T14:07:46.001Z",
      "sent_at": "2026-09-29T10:15:00.642Z",
      "expires_at": "2026-10-13T21:59:59.999Z",
      "accepted_at": "2026-10-02T14:07:45.912Z",
      "expired_at": null,
      "version": 1,
      "recipient": { "name": "John Smith", "company": "Sample AG", "email": "john@example.com" },
      "accepted_by": { "name": "John Smith", "email": "john@example.com" },
      "value": { "amount": 1250000, "currency": "EUR" }
    },
    "event": {
      "sequence": 7,
      "type": "accepted",
      "occurred_at": "2026-10-02T14:07:45.912Z",
      "version": 1,
      "data": { "signer_email": "john@example.com" }
    }
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 5 * 60;

/**
 * @param {string} secret   The endpoint secret, "whsec_..."
 * @param {Record<string, string>} headers  Request headers, lower-cased names
 * @param {string | Buffer} rawBody  The request body exactly as received
 */
export function verifyHocDocWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;

  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;

  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest();

  return signatures.split(" ").some((entry) => {
    const [version, value] = entry.split(",");
    if (version !== "v1" || !value) return false;
    const given = Buffer.from(value, "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 5 * 60


def verify_hocdoc_webhook(secret: str, headers: dict[str, str], raw_body: bytes) -> bool:
    """secret: the endpoint secret, "whsec_...". headers: lower-cased names. raw_body: bytes as received."""
    webhook_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not webhook_id or not timestamp or not signatures:
        return False

    try:
        age = abs(time.time() - int(timestamp))
    except ValueError:
        return False
    if age > TOLERANCE_SECONDS:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{webhook_id}.{timestamp}.".encode() + raw_body
    expected = hmac.new(key, signed, hashlib.sha256).digest()

    for entry in signatures.split(" "):
        version, _, value = entry.partition(",")
        if version != "v1" or not value:
            continue
        try:
            given = base64.b64decode(value)
        except ValueError:
            continue
        if hmac.compare_digest(given, expected):
            return True
    return False