DocTransform

Verificar webhooks

Confira que cada evento veio mesmo da DocTransform e que não foi alterado nem repetido

Quem souber o endereço do seu webhook poderia mandar eventos falsos para ele. A DocTransform assina cada evento, e o seu código confere essa assinatura antes de confiar no conteúdo. Pule esta página se você usa Zapier, Make ou n8n: eles não precisam disso. Webhooks são novidade para você? Comece por Webhooks.

Cabeçalhos que enviamos

Assinamos com Standard Webhooks, o esquema que OpenAI, Twilio e Resend também usam, então qualquer biblioteca dele pode nos verificar. Cada evento leva estes cabeçalhos:

CabeçalhoO que contém
webhook-idO id do evento. É o mesmo em cada nova tentativa e em cada reenvio.
webhook-timestampA hora desta tentativa, em segundos Unix.
webhook-signatureUma ou mais entradas v1,<base64> separadas por espaços. São duas enquanto um segredo está sendo trocado.
content-typeapplication/json
user-agentDocTransform-Webhooks/1

Verificar com uma biblioteca

Este é o caminho mais curto. Guarde o seu segredo de assinatura numa variável de ambiente chamada DOCTRANSFORM_WEBHOOK_SECRET, nunca no código. Cole o valor como a tela do webhook o mostra, começando por whsec_. Em 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)

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

Se verify falhar, responda 400. Se funcionar, responda rápido um 2xx e faça o trabalho depois. Também existem bibliotecas para Go, Ruby, PHP, Java e Kotlin, Rust, C# e Elixir: veja a lista de bibliotecas do Standard Webhooks.

Ler o corpo bruto

Atenção Verifique exatamente os bytes que recebeu, antes que qualquer analisador de JSON toque neles.

Um analisador pode mudar espaços ou a ordem das chaves, e então a assinatura deixa de bater. No 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
});

No 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

No 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

Num route handler do Next.js, use await req.text(). Numa plataforma serverless que pode codificar o corpo em base64, decodifique-o primeiro.

Verificar à mão

Sem biblioteca? Cinco passos, em qualquer linguagem:

  1. Monte o texto assinado

    Junte o webhook-id, o webhook-timestamp e o corpo bruto com um ponto entre cada um: <id>.<timestamp>.<body>.

  2. Decodifique a chave

    Pegue a parte do segredo depois de whsec_ e decodifique-a de base64.

  3. Assine

    Calcule um HMAC-SHA256 do texto com essa chave e codifique o resultado em base64.

  4. Compare

    Compare-o com cada entrada v1, de webhook-signature, em tempo constante.

  5. Aceite se alguma bater

    Basta uma entrada que bata. Se nenhuma bater, recuse.

Em Python, sem dependências:

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")

Em Node.js, sem dependências:

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

Impedir repetições e duplicatas

Recuse um webhook-timestamp a mais de 5 minutos do seu relógio. As bibliotecas fazem isso por padrão: nunca desligue. Guarde também cada webhook-id já tratado e responda 2xx sem agir de novo diante de uma repetição. A entrega é «pelo menos uma vez», então uma repetição é normal. É o par, do lado do receptor, da Idempotency-Key nas execuções.

Alterar o segredo de assinatura

Abra o webhook, clique em Alterar segredo e copie o novo. O segredo antigo continua valendo por 24 horas, e cada evento leva as duas assinaturas nesse meio-tempo, então atualize o seu servidor a qualquer hora desse dia. Se o segredo antigo vazou, clique em Parar o segredo antigo agora.