Vérifier les webhooks
Vérifiez que chaque événement vient bien de DocTransform et n’a été ni modifié ni rejoué
Quiconque connaît l’adresse de votre webhook pourrait lui envoyer de faux événements. DocTransform signe chaque événement, et votre code vérifie cette signature avant de se fier au contenu. Passez cette page si vous utilisez Zapier, Make ou n8n : ils n’en ont pas besoin. Les webhooks sont nouveaux pour vous ? Commencez par Webhooks.
En-têtes que nous envoyons
Nous signons avec Standard Webhooks, le schéma que OpenAI, Twilio et Resend utilisent aussi, donc n’importe laquelle de ses bibliothèques peut nous vérifier. Chaque événement porte ces en-têtes :
| En-tête | Ce qu’il contient |
|---|---|
webhook-id | L’identifiant de l’événement. Il est le même à chaque nouvelle tentative et à chaque renvoi. |
webhook-timestamp | L’heure de cette tentative, en secondes Unix. |
webhook-signature | Une ou plusieurs entrées v1,<base64> séparées par des espaces. Il y en a deux pendant qu’un secret est changé. |
content-type | application/json |
user-agent | DocTransform-Webhooks/1 |
Vérifier avec une bibliothèque
C’est le chemin le plus court. Gardez votre secret de signature dans une variable d’environnement nommée DOCTRANSFORM_WEBHOOK_SECRET, jamais dans le code. Collez la valeur telle que l’écran du webhook l’affiche, en commençant par whsec_. En 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)En 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);
}Si verify échoue, répondez 400. Si cela marche, répondez vite par un 2xx et faites le travail ensuite. Des bibliothèques existent aussi pour Go, Ruby, PHP, Java et Kotlin, Rust, C# et Elixir : voir la liste des bibliothèques Standard Webhooks.
Lire le corps brut
Un analyseur peut changer les espaces ou l’ordre des clés, et la signature ne correspond plus. Avec 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
});Avec 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 afterwardsAvec 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 afterwardsDans un route handler Next.js, utilisez await req.text(). Sur une plateforme serverless qui peut encoder le corps en base64, décodez-le d’abord.
Vérifier à la main
Pas de bibliothèque ? Cinq étapes, dans n’importe quel langage :
Construisez le texte signé
Joignez le
webhook-id, lewebhook-timestampet le corps brut avec un point entre chaque :<id>.<timestamp>.<body>.Décodez la clé
Prenez la partie du secret après
whsec_et décodez-la depuis le base64.Signez
Calculez un HMAC-SHA256 du texte avec cette clé, puis encodez le résultat en base64.
Comparez
Comparez-le à chaque entrée
v1,dewebhook-signature, en temps constant.Acceptez au premier accord
Une seule entrée qui correspond suffit. Aucune ne correspond : refusez.
En Python, sans dépendance :
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")En Node.js, sans dépendance :
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');
}Bloquer les rejeux et les doublons
Refusez un webhook-timestamp à plus de 5 minutes de votre horloge. Les bibliothèques le font par défaut : ne le désactivez jamais. Gardez aussi chaque webhook-id déjà traité, et répondez 2xx sans agir de nouveau sur une répétition. La livraison est « au moins une fois », une répétition est donc normale. C’est le pendant, côté récepteur, de l’Idempotency-Key sur les exécutions.
Changer le secret de signature
Ouvrez le webhook, cliquez sur Changer le secret et copiez le nouveau. Votre ancien secret reste valable 24 heures, et chaque événement porte les deux signatures entre-temps : mettez votre serveur à jour à n’importe quel moment de cette journée. Si l’ancien secret a fuité, cliquez sur Arrêter l’ancien secret maintenant.