Passar o receptor para assinaturas Standard Webhooks
Cada entrega de webhook passa a ser assinada com os cabeçalhos webhook-id, webhook-timestamp e webhook-signature e um segredo whsec_. O que muda no seu receptor, como verificar e como trocar o segredo sem perder eventos.
O que mudou#
As entregas de webhook deixaram de levar os cabeçalhos X- com prefixo do fornecedor para a assinatura e o identificador do evento. Cada POST para o seu endpoint segue agora a especificação Standard Webhooks e envia três cabeçalhos:
| Cabeçalho | Valor |
|---|---|
webhook-id |
O identificador da entrega, com prefixo dlv_. Mantém-se igual nas novas tentativas automáticas e nas repetições manuais, por isso sirva-se dele para descartar duplicados. |
webhook-timestamp |
Hora Unix, em segundos, do início desta tentativa. Cada nova tentativa recebe outro timestamp e outra assinatura. |
webhook-signature |
Um ou mais tokens v1,<base64> separados por um espaço. |
A assinatura é um HMAC-SHA256 sobre o texto webhook-id.webhook-timestamp.corpo, em que o corpo é o pedido em bruto, tal como chegou. A chave obtém-se tirando o prefixo whsec_ ao segredo e descodificando o resto em base64. Os segredos têm 32 bytes aleatórios, pelo que os recebe como whsec_ seguido de 44 caracteres base64.
Antes e depois#
O código antigo lia um único cabeçalho de assinatura. O novo precisa dos três valores e do corpo em bruto:
import crypto from "node:crypto";
export function verify(headers, rawBody, secret) {
const id = headers["webhook-id"];
const ts = headers["webhook-timestamp"];
const sig = headers["webhook-signature"];
if ([id, ts, sig].some((value) => value === undefined)) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = crypto.createHmac("sha256", key)
.update(`${id}.${ts}.`).update(rawBody).digest();
return sig.trim().split(/\s+/).some((token) => {
const [version, b64] = token.split(",", 2);
const candidate = Buffer.from(b64 || "", "base64");
return version === "v1" && candidate.length === expected.length
&& crypto.timingSafeEqual(candidate, expected);
});
}
Aceite o pedido quando qualquer um dos tokens coincidir. A janela de 300 segundos é a dos exemplos de receptor em Node.js, Python e Go; ajuste-a se os relógios dos seus servidores se desviarem, mas mantenha um limite para que um pedido antigo, capturado por terceiros, não possa ser reenviado.
Uma entrega chega assim:
POST /hook HTTP/1.1
Content-Type: application/json
webhook-id: dlv_2Kxa1bR8mTqN5vWz3HcJ7pLsE0d
webhook-timestamp: 1795075200
webhook-signature: v1,K5oZfzN95Z9Zl5Zl1ZgL4jYy8V9ZtqzF3JtM5YhJ1Wk=
O corpo traz o evento: id (identificador wev_), type, api_version, tenant_id, created_at e data.
Trocar o segredo durante a migração#
Se não tem a certeza de qual segredo o receptor guarda, gere um novo. A operação rollDeveloperWebhookSecret exige o âmbito developer:write. O campo overlap_seconds define durante quanto tempo o segredo antigo continua a assinar ao lado do novo, de 0 a 604800, e por omissão vale 86400.
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_2Kx9fQmZ7pLwR4tYb8NcV1sD3eH/roll" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"overlap_seconds": 86400}'
{
"id": "whk_2Kx9fQmZ7pLwR4tYb8NcV1sD3eH",
"url": "https://erp.example.test/hook",
"description": "Sincronização de facturas",
"events": ["invoice.issued", "invoice.paid"],
"enabled": true,
"health": "healthy",
"created_at": "2026-10-02T08:14:00Z",
"updated_at": "2026-11-19T09:30:00Z",
"previous_secret_expires_at": "2026-11-20T09:30:00Z",
"secret": "whsec_Q2v8nR4kT1mZ7xY0pL3sW6bH9dF2gJ5cN8aE1uK4iO0="
}
A resposta é 201. Além da criação do endpoint, é a única resposta que traz o campo secret, por isso guarde-o de imediato. Até previous_secret_expires_at, o webhook-signature leva dois tokens, um por segredo; é por isso que a verificação tem de experimentar todos. Com o valor 0, o segredo antigo deixa logo de valer e as entregas voltam a levar um só token. Um valor fora do intervalo devolve 400; um endpoint que não existe devolve 404.
Confirmar a integração#
Execute gotactl webhooks listen --forward-to http://localhost:3000/hook. A opção --forward-to indica o URL local que recebe os POST reencaminhados. O CLI mostra um segredo whsec_ novo para a sessão e assina cada evento com os mesmos três cabeçalhos, usando o identificador do evento como webhook-id. Com um sandbox como contexto activo, execute noutro terminal gotactl events trigger invoice.paid e confirme que o receptor responde 200. Para testar o percurso real até um endpoint já publicado, chame POST $BUSINESS_API/developer/webhooks/{id}/test: fica em fila um evento de exemplo e a resposta 202 devolve a entrega com o estado pending. Um endpoint desactivado ou em pausa devolve 409; active-o ou retome-o antes.
Veja como verificar assinaturas para as versões em Python e Go, e a visão geral dos webhooks para as novas tentativas e os estados das entregas.