DocTransform

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êteCe qu’il contient
webhook-idL’identifiant de l’événement. Il est le même à chaque nouvelle tentative et à chaque renvoi.
webhook-timestampL’heure de cette tentative, en secondes Unix.
webhook-signatureUne ou plusieurs entrées v1,<base64> séparées par des espaces. Il y en a deux pendant qu’un secret est changé.
content-typeapplication/json
user-agentDocTransform-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 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)

En 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);
}

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

Attention Vérifiez exactement les octets reçus, avant que tout analyseur JSON n’y touche.

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 afterwards

Avec 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

Dans 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 :

  1. Construisez le texte signé

    Joignez le webhook-id, le webhook-timestamp et le corps brut avec un point entre chaque : <id>.<timestamp>.<body>.

  2. Décodez la clé

    Prenez la partie du secret après whsec_ et décodez-la depuis le base64.

  3. Signez

    Calculez un HMAC-SHA256 du texte avec cette clé, puis encodez le résultat en base64.

  4. Comparez

    Comparez-le à chaque entrée v1, de webhook-signature, en temps constant.

  5. 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.