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çalho | O que contém |
|---|---|
webhook-id | O id do evento. É o mesmo em cada nova tentativa e em cada reenvio. |
webhook-timestamp | A hora desta tentativa, em segundos Unix. |
webhook-signature | Uma ou mais entradas v1,<base64> separadas por espaços. São duas enquanto um segredo está sendo trocado. |
content-type | application/json |
user-agent | DocTransform-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 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)Em 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);
}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
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 afterwardsNo 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 afterwardsNum 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:
Monte o texto assinado
Junte o
webhook-id, owebhook-timestampe o corpo bruto com um ponto entre cada um:<id>.<timestamp>.<body>.Decodifique a chave
Pegue a parte do segredo depois de
whsec_e decodifique-a de base64.Assine
Calcule um HMAC-SHA256 do texto com essa chave e codifique o resultado em base64.
Compare
Compare-o com cada entrada
v1,dewebhook-signature, em tempo constante.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.