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:
| Header | Was er enthält |
|---|---|
webhook-id | Die ID des Ereignisses. Sie ist bei jeder Wiederholung und jedem erneuten Senden gleich. |
webhook-timestamp | Der Zeitpunkt dieses Versuchs in Unix-Sekunden. |
webhook-signature | Ein oder mehrere Einträge v1,<base64>, durch Leerzeichen getrennt. Es sind zwei, während ein Geheimnis geändert wird. |
content-type | application/json |
user-agent | DocTransform-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 standardwebhooksimport 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 standardwebhooksimport { 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
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 afterwardsIn 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 afterwardsIn 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:
Den signierten Text bauen
Verbinde
webhook-id,webhook-timestampund den Rohinhalt mit je einem Punkt dazwischen:<id>.<timestamp>.<body>.Den Schlüssel dekodieren
Nimm den Teil des Geheimnisses nach
whsec_und dekodiere ihn aus base64.Signieren
Berechne ein HMAC-SHA256 des Textes mit diesem Schlüssel und kodiere es in base64.
Vergleichen
Vergleiche es mit jedem
v1,-Eintrag vonwebhook-signature, in konstanter Zeit.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.