Boas práticas para receptores de webhooks
Verifique o corpo em bruto, responda em menos de 10 segundos, elimine duplicados pelo webhook-id, descarte alterações antigas com data.resource.sequence, escolha bem o código de estado e rode segredos com sobreposição.
O processo de entrega foi feito para poder repetir sem riscos, o que significa que o seu receptor vai por vezes receber a mesma entrega duas vezes e tem de lidar com isso. As regras abaixo decorrem do comportamento real desse processo.
Verificar antes de interpretar#
Calcule a assinatura sobre os bytes recebidos, e não sobre um JSON que interpretou e voltou a serializar: a ordem das chaves e os espaços alteram o resultado. Recuse um webhook-timestamp com mais de alguns minutos. A página de verificação tem código para Node.js, Python e Go.
Responder depressa, processar depois#
O processo de entrega espera no máximo 10 segundos pela resposta e depois dá a tentativa como falhada. Guarde o corpo, responda 200 e faça o trabalho demorado (actualizar o ERP, enviar emails) a partir da sua própria fila.
Eliminar duplicados pelo webhook-id#
O webhook-id é o identificador dlv_ da entrega. Mantém-se igual nas novas tentativas automáticas, num Reenviar manual e num reenvio em lote. Guarde os identificadores já tratados e ignore os repetidos. Se vários endereços seus subscreverem o mesmo evento, cada um recebe a sua própria entrega; nesse caso, a chave comum é o id do evento (wev_).
app.post("/hooks/billing", express.raw({ type: "application/json" }), async (req, res) => {
const valid = verifyWebhook(req.body.toString("utf8"), req.headers, process.env.WEBHOOK_SECRET);
if (valid === false) return res.status(401).end();
const deliveryId = req.headers["webhook-id"];
if (await seen.has(deliveryId)) return res.status(200).end();
const event = JSON.parse(req.body);
const last = await sequences.get(event.data.resource.type, event.data.resource.id);
if (event.data.resource.sequence > (last ?? 0)) {
await jobs.enqueue(event);
}
await seen.add(deliveryId);
res.status(200).end();
});
Confiar na sequência, não na hora de chegada#
Para o mesmo endereço, as entregas sobre um registo seguem por ordem: a seguinte espera enquanto a anterior estiver pendente ou guardada, e segue quando essa for concluída, falhar ou for cancelada. Registos diferentes não esperam uns pelos outros, e uma entrega guardada ou reenviada pode chegar depois de já ter avançado. data.resource.sequence conta os eventos de cada registo; ignore o que não for mais recente do que aquilo que já aplicou, ou leia o registo na API quando precisar do estado actual.
Escolher o código de estado de propósito#
5xx, 408, 425 e 429 significam "tente mais tarde". Qualquer outro 4xx pára a entrega ao fim de duas tentativas e guarda-a como paused. 410 Gone pausa o endereço inteiro e guarda tudo o que estava na fila para ele. Responda 410 apenas quando quiser mesmo deixar de receber.
Rodar segredos com sobreposição#
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ/roll" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"overlap_seconds": 86400}'
{
"id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"url": "https://erp.example.test/hooks/billing",
"description": "Sincronização da facturação com o ERP",
"events": ["invoice.paid", "payment.received"],
"enabled": true,
"secret": "whsec_vQPM6Bhi6UrlK4RSGJDD11Kz8F6kc5T8pC/smJkBVPA=",
"created_by": "usr_2mB4tK9qWx1RfZ7nLc3VhP8sDjE",
"created_at": "2026-11-19T08:02:41.118204Z",
"updated_at": "2026-11-19T11:40:03.551870Z",
"previous_secret_expires_at": "2026-11-20T11:40:03.551870Z",
"health": "healthy",
"consecutive_failures": 0,
"api_version": "v1"
}
Até previous_secret_expires_at, o cabeçalho webhook-signature leva uma assinatura v1, por segredo, separadas por um espaço, para que um receptor com qualquer dos dois segredos continue a aceitar as entregas. Sem corpo no pedido, a sobreposição é de 24 horas; overlap_seconds vai de 0 (o segredo antigo deixa de valer de imediato) a 604800 (7 dias). No painel, esta acção chama-se Rodar segredo.
Recuperar depois de uma falha#
Por omissão, os eventos ficam disponíveis durante 90 dias. GET $BUSINESS_API/developer/events aceita type, resource_type, resource_id, from e to, o que permite comparar o que guardou com o que aconteceu.