Webhooks

curl https://api-eu.dynamicdocumentapi.com/v1/webhook-endpoints \
  -H "Authorization: Bearer $DYNAMIC_DOCUMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/documents",
    "description": "Invoice renders",
    "events": ["render.succeeded", "render.failed"],
    "enabled": true
  }'

POST /webhooks/documents HTTP/1.1
content-type: application/json
webhook-id: evt_01J9ZM4T6W8Y0A2C4E6G8J0K2M
webhook-timestamp: 1789657594
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
user-agent: Dynamic-Document-Api-Webhooks/1.0

{
  "id": "evt_01J9ZM4T6W8Y0A2C4E6G8J0K2M",
  "type": "render.succeeded",
  "created_at": "2026-09-17T15:06:34Z",
  "workspace_id": "ws_01J9ZK0P2R4T6V8X0Z2B4D6F8H",
  "region": "eu",
  "data": {
    "object": {
      "id": "rnd_01J9ZM1X3F7R8K2C4V6B8N0P2Q",
      "object": "render",
      "status": "succeeded",
      "reference": "inv_2026_0042",
      "files": [{ "id": "file_01J9ZM4T6W8Y0A2C4E6G8J0K2M", "format": "pdf", "pages": 2, "url": "https://files-eu.dynamicdocumentapi.com/f/…" }]
    }
  }
}

{
  "input": { "type": "template", "template_id": "tpl_01J9ZK3M7Q8V5W2X4Y6Z8A0B1C" },
  "data": { "number": "2026-0042" },
  "mode": "async",
  "webhook": {
    "url": "https://example.com/webhooks/documents",
    "events": ["render.succeeded", "render.failed"]
  }
}

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

const TOLERANCE_SECONDS = 5 * 60;

/**
 * Verifies a webhook delivery (Standard Webhooks) and returns the parsed event.
 * Throws if a header is missing, the timestamp is outside the tolerance or no signature matches.
 *
 * @param {Buffer | Uint8Array | string} rawBody The request body exactly as received.
 * @param {Record<string, string | string[] | undefined>} headers Request headers with lower-case names.
 * @param {string} secret The endpoint's signing secret ("whsec_…").
 */
export function verifyWebhook(rawBody, headers, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (typeof id !== "string" || typeof timestamp !== "string" || typeof signatures !== "string") {
    throw new Error("Missing webhook headers");
  }

  const now = Math.floor(Date.now() / 1000);
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) {
    throw new Error("Webhook timestamp is invalid or outside the tolerance");
  }

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

  for (const entry of signatures.split(" ")) {
    const comma = entry.indexOf(",");
    if (comma === -1 || entry.slice(0, comma) !== "v1") continue;
    const received = Buffer.from(entry.slice(comma + 1));
    if (received.length === expected.length && timingSafeEqual(received, expected)) {
      return JSON.parse(body.toString("utf8"));
    }
  }
  throw new Error("No matching webhook signature");
}

import express from "express";

import { verifyWebhook } from "./verify-webhook.mjs";

const app = express();

app.post("/webhooks/documents", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = verifyWebhook(req.body, req.headers, process.env.DYNAMIC_DOCUMENT_API_WEBHOOK_SECRET);
  } catch {
    return res.status(400).send("invalid webhook");
  }

  if (event.type === "render.succeeded") {
    const render = event.data.object;
    console.log(`Render ${render.id} finished with ${render.files.length} file(s)`);
  }
  res.sendStatus(204);
});

app.listen(3000);

import base64
import hashlib
import hmac
import json
import time

TOLERANCE_SECONDS = 5 * 60


class WebhookVerificationError(Exception):
    """Raised when a webhook delivery cannot be verified."""


def verify_webhook(raw_body: bytes, headers, secret: str) -> dict:
    """Verify a webhook delivery (Standard Webhooks) and return the parsed event.

    raw_body -- the request body exactly as received (bytes)
    headers  -- request headers; Flask and Django header objects work as-is,
                a plain dict needs lower-case names
    secret   -- the endpoint's signing secret ("whsec_...")
    """
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures:
        raise WebhookVerificationError("missing webhook headers")

    if not timestamp.isdecimal() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        raise WebhookVerificationError("webhook timestamp is invalid or outside the tolerance")

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

    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature.encode(), expected):
            return json.loads(raw_body)
    raise WebhookVerificationError("no matching webhook signature")