DocTransform

Webhooks prüfen

Prüfe, dass jedes Ereignis wirklich von DocTransform kommt und weder verändert noch wiederholt wurde

Wer die Adresse deines Webhooks kennt, könnte ihr gefälschte Ereignisse schicken. DocTransform signiert jedes Ereignis, und dein Code prüft diese Signatur, bevor er dem Inhalt traut. Überspringe diese Seite, wenn du Zapier, Make oder n8n nutzt: Sie brauchen das nicht. Neu bei Webhooks? Beginne mit Webhooks.

Header, die wir senden

Wir signieren mit Standard Webhooks, dem Verfahren, das auch OpenAI, Twilio und Resend nutzen, daher kann jede seiner Bibliotheken uns prüfen. Jedes Ereignis trägt diese Header:

HeaderWas er enthält
webhook-idDie ID des Ereignisses. Sie ist bei jeder Wiederholung und jedem erneuten Senden gleich.
webhook-timestampDer Zeitpunkt dieses Versuchs in Unix-Sekunden.
webhook-signatureEin oder mehrere Einträge v1,<base64>, durch Leerzeichen getrennt. Es sind zwei, während ein Geheimnis geändert wird.
content-typeapplication/json
user-agentDocTransform-Webhooks/1

Mit einer Bibliothek prüfen

Das ist der kürzeste Weg. Lege dein Signaturgeheimnis in einer Umgebungsvariable namens DOCTRANSFORM_WEBHOOK_SECRET ab, nie im Code. Füge den Wert so ein, wie der Webhook-Bildschirm ihn zeigt, beginnend mit whsec_. In Python:

pip install standardwebhooks
import os

from standardwebhooks import Webhook


def verify(raw_body, headers):
    # Pass the secret exactly as the Webhook screen shows it, whsec_ included.
    secret = os.environ["DOCTRANSFORM_WEBHOOK_SECRET"]
    # Raises if the signature is wrong or the timestamp is older than 5 minutes.
    return Webhook(secret).verify(raw_body, headers)

In Node.js:

npm install standardwebhooks
import { Webhook } from 'standardwebhooks';

export function verify(rawBody, headers) {
  // Pass the secret exactly as the Webhook screen shows it, whsec_ included.
  const secret = process.env.DOCTRANSFORM_WEBHOOK_SECRET;
  // Throws if the signature is wrong or the timestamp is older than 5 minutes.
  return new Webhook(secret).verify(rawBody, headers);
}

Schlägt verify fehl, antworte mit 400. Klappt es, antworte schnell mit einem 2xx und erledige die Arbeit danach. Bibliotheken gibt es auch für Go, Ruby, PHP, Java und Kotlin, Rust, C# und Elixir: siehe die Bibliotheksliste von Standard Webhooks.

Den Rohinhalt lesen

Achtung Prüfe genau die empfangenen Bytes, bevor ein JSON-Parser sie anfasst.

Ein Parser kann Leerzeichen oder die Reihenfolge der Schlüssel ändern, und dann passt die Signatur nicht mehr. In Express:

import { verify } from './verifyLibrary.mjs';

// express.raw keeps the exact bytes. Put it on this route before express.json().
app.post('/doctransform', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    verify(req.body, req.headers);
  } catch {
    return res.sendStatus(400);
  }
  res.sendStatus(200); // answer fast, do the work afterwards
});

In FastAPI:

from fastapi import FastAPI, HTTPException, Request
from verify_library import verify

app = FastAPI()


@app.post("/doctransform")
async def doctransform(request: Request):
    raw_body = await request.body()  # the bytes, never a parsed model
    try:
        verify(raw_body, dict(request.headers))
    except Exception:
        raise HTTPException(status_code=400)
    return {"ok": True}  # answer fast, do the work afterwards

In Flask:

from flask import Flask, abort, request
from verify_library import verify

app = Flask(__name__)


@app.post("/doctransform")
def doctransform():
    raw_body = request.get_data()  # the bytes, before any JSON parsing
    try:
        verify(raw_body, dict(request.headers))
    except Exception:
        abort(400)
    return "", 200  # answer fast, do the work afterwards

In einem Next.js-Route-Handler nutze await req.text(). Auf einer Serverless-Plattform, die den Inhalt base64-kodieren kann, dekodiere ihn zuerst.

Von Hand prüfen

Keine Bibliothek? Fünf Schritte, in jeder Sprache:

  1. Den signierten Text bauen

    Verbinde webhook-id, webhook-timestamp und den Rohinhalt mit je einem Punkt dazwischen: <id>.<timestamp>.<body>.

  2. Den Schlüssel dekodieren

    Nimm den Teil des Geheimnisses nach whsec_ und dekodiere ihn aus base64.

  3. Signieren

    Berechne ein HMAC-SHA256 des Textes mit diesem Schlüssel und kodiere es in base64.

  4. Vergleichen

    Vergleiche es mit jedem v1,-Eintrag von webhook-signature, in konstanter Zeit.

  5. Bei einem Treffer annehmen

    Ein passender Eintrag genügt. Passt keiner, lehne ab.

In Python, ohne Abhängigkeiten:

import base64
import hashlib
import hmac
import json
import os
import time


def verify(raw_body, headers):
    secret = os.environ["DOCTRANSFORM_WEBHOOK_SECRET"]
    event_id = headers["webhook-id"]
    timestamp = headers["webhook-timestamp"]

    # Reject a message more than 5 minutes from your clock.
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("timestamp outside 5 minutes")

    # Sign "<id>.<timestamp>.<raw body>" with the key inside the secret.
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{event_id}.{timestamp}.".encode() + raw_body
    digest = hmac.new(key, signed, hashlib.sha256).digest()
    expected = base64.b64encode(digest).decode()

    # The header holds one "v1,<signature>" per live secret. Any match is enough.
    for entry in headers["webhook-signature"].split():
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return json.loads(raw_body)
    raise ValueError("signature does not match")

In Node.js, ohne Abhängigkeiten:

import crypto from 'node:crypto';

export function verify(rawBody, headers) {
  const secret = process.env.DOCTRANSFORM_WEBHOOK_SECRET;
  const eventId = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];

  // Reject a message more than 5 minutes from your clock.
  const seconds = Number(timestamp);
  if (!Number.isFinite(seconds) || Math.abs(Date.now() / 1000 - seconds) > 300) {
    throw new Error('timestamp outside 5 minutes');
  }

  // Sign "<id>.<timestamp>.<raw body>" with the key inside the secret.
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = crypto
    .createHmac('sha256', key)
    .update(`${eventId}.${timestamp}.`)
    .update(rawBody)
    .digest();

  // The header holds one "v1,<signature>" per live secret. Any match is enough.
  for (const entry of headers['webhook-signature'].split(' ')) {
    const [version, signature = ''] = entry.split(',');
    const given = Buffer.from(signature, 'base64');
    if (
      version === 'v1' &&
      given.length === expected.length &&
      crypto.timingSafeEqual(given, expected)
    ) {
      return JSON.parse(rawBody);
    }
  }
  throw new Error('signature does not match');
}

Wiederholungen und Duplikate stoppen

Lehne einen webhook-timestamp ab, der mehr als 5 Minuten von deiner Uhr abweicht. Die Bibliotheken tun das standardmäßig: schalte es nie ab. Speichere außerdem jede webhook-id, die du verarbeitet hast, und antworte bei einer Wiederholung mit 2xx, ohne erneut zu handeln. Die Zustellung gilt „mindestens einmal“, eine Wiederholung ist also normal. Es ist das Gegenstück beim Empfänger zum Idempotency-Key bei Läufen.

Das Signaturgeheimnis ändern

Öffne den Webhook, klicke auf Geheimnis ändern und kopiere das neue. Dein altes Geheimnis gilt noch 24 Stunden, und jedes Ereignis trägt in der Zeit beide Signaturen, aktualisiere deinen Server also irgendwann an diesem Tag. Ist das alte Geheimnis durchgesickert, klicke auf Altes Geheimnis jetzt beenden.