Verificar assinaturas de webhooks
Confirme que cada entrega veio da sua conta com os cabeçalhos webhook-id, webhook-timestamp e webhook-signature e o segredo whsec_ do endpoint.
Cada entrega de webhook chega assinada segundo a especificação Standard Webhooks. Antes de processar o evento, o seu servidor recalcula a assinatura com o segredo do endpoint e compara-a com a que veio no pedido. Pode usar o código desta página ou qualquer biblioteca Standard Webhooks, que aceita o segredo whsec_ tal como o recebe.
O segredo de assinatura#
O segredo é devolvido uma única vez, no campo secret, na resposta de POST $BUSINESS_API/developer/webhooks (criar o endpoint) e de POST $BUSINESS_API/developer/webhooks/{id}/roll (renovar o segredo). Leituras posteriores do endpoint não o incluem, por isso guarde-o logo num cofre de segredos.
O formato é whsec_ seguido de 32 bytes aleatórios em base64. A chave HMAC são esses 32 bytes: retire o prefixo e descodifique o resto antes de assinar.
Os três cabeçalhos#
| Cabeçalho | Conteúdo |
|---|---|
webhook-id |
Identificador da entrega (dlv_). É o mesmo em todas as tentativas da mesma entrega; use-o para ignorar duplicados. |
webhook-timestamp |
Segundos Unix do início da tentativa. Cada nova tentativa traz um valor novo e, portanto, uma assinatura nova. |
webhook-signature |
Uma ou mais assinaturas v1,<base64> separadas por espaços. |
A assinatura é o HMAC-SHA256 da cadeia webhook-id + . + webhook-timestamp + . + corpo, codificado em base64. O corpo tem de ser exactamente os bytes recebidos: se o seu framework fizer o parse do JSON e o voltar a serializar, a comparação falha.
Exemplo de entrega#
Este é um pedido real de um evento webhook.test, assinado com o segredo whsec_bxwqm+TQP3pRyOK5bUCn8xhc6bIEfabzwehbKdB/Sm4=. Pode usá-lo como caso de teste para o seu código:
POST /hooks/billing HTTP/1.1
Content-Type: application/json
User-Agent: Gota-Webhooks/1.0
webhook-id: dlv_2pR8kF6wNz1QcT4bVx7LmHs9JdR
webhook-timestamp: 1795079647
webhook-signature: v1,wWR3EcUtcs9smHNXisdbsUP5PNZ7xWNciZy+vbXESW4=
{"api_version":"v1","created_at":"2026-11-19T09:14:07.512Z","data":{"attributes":{"message":"This is a test event."},"resource":{"id":"whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF","sequence":1,"type":"webhook"},"resource_id":"whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF","resource_type":"webhook"},"id":"wev_2pR8kD3vXq6NtB9wLc5YmJs2HaE","tenant_id":"ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF","type":"webhook.test"}
Como o timestamp já passou, desligue a verificação da janela de tempo enquanto usa este pedido num teste unitário.
Verificar em código#
As três versões fazem o mesmo: rejeitam pedidos sem os cabeçalhos, rejeitam timestamps a mais de 300 segundos do relógio do servidor (a janela de cinco minutos que a especificação recomenda contra repetições) e comparam as assinaturas em tempo constante.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWebhook(rawBody, headers, secret) {
const id = headers["webhook-id"];
const ts = headers["webhook-timestamp"];
const sigHeader = headers["webhook-signature"];
if ([id, ts, sigHeader].some((v) => v === undefined || v === "")) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = createHmac("sha256", key)
.update(Buffer.concat([Buffer.from(`${id}.${ts}.`), rawBody]))
.digest();
return sigHeader.trim().split(/\s+/).some((entry) => {
const [version, b64] = entry.split(",", 2);
if (version === "v1" && b64) {
const candidate = Buffer.from(b64, "base64");
return candidate.length === expected.length && timingSafeEqual(candidate, expected);
}
return false;
});
}
import base64, hashlib, hmac, time
def verify_webhook(raw_body: bytes, headers: dict, secret: str) -> bool:
wid = headers.get("webhook-id")
ts = headers.get("webhook-timestamp")
sig_header = headers.get("webhook-signature")
if not (wid and ts and sig_header):
return False
if abs(time.time() - int(ts)) > 300:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
digest = hmac.new(key, f"{wid}.{ts}.".encode() + raw_body, hashlib.sha256).digest()
expected = "v1," + base64.b64encode(digest).decode()
return any(hmac.compare_digest(part, expected) for part in sig_header.split())
func verifyWebhook(rawBody []byte, h http.Header, secret string) bool {
id, ts, sigs := h.Get("webhook-id"), h.Get("webhook-timestamp"), h.Get("webhook-signature")
sec, tsErr := strconv.ParseInt(ts, 10, 64)
key, keyErr := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
fresh := tsErr == nil && math.Abs(time.Since(time.Unix(sec, 0)).Seconds()) <= 300
if fresh && keyErr == nil && len(id) > 0 && len(sigs) > 0 {
mac := hmac.New(sha256.New, key)
mac.Write([]byte(id + "." + ts + "."))
mac.Write(rawBody)
expected := "v1," + base64.StdEncoding.EncodeToString(mac.Sum(nil))
for _, part := range strings.Fields(sigs) {
if hmac.Equal([]byte(part), []byte(expected)) {
return true
}
}
}
return false
}
Responder a uma assinatura inválida#
Responda com um código 4xx e não processe o evento. Do lado do envio, uma resposta 4xx comum só é repetida poucas vezes; depois a entrega fica no estado paused, à espera que corrija o endpoint, e uma resposta 410 coloca-a em pausa logo à primeira. Depois de corrigir a verificação, reenvie as entregas em pausa com Reenviar falhadas na página do webhook ou com POST $BUSINESS_API/developer/webhooks/{id}/redeliveries, que por omissão abrange as entregas falhadas e em pausa das últimas 24 horas e aceita uma janela até 7 dias.
Renovar o segredo sem perder entregas#
Renovar o segredo exige o scope developer:write. O campo opcional overlap_seconds define durante quanto tempo o segredo anterior continua a assinar, de 0 a 604800 segundos, com 86400 por omissão; 0 retira o segredo antigo de imediato.
curl -X POST $BUSINESS_API/developer/webhooks/whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF/roll \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"overlap_seconds": 3600}'
{
"id": "whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF",
"url": "https://erp.example.test/hooks/billing",
"description": "Sincronização de facturas",
"events": ["invoice.paid", "payment.received"],
"enabled": true,
"created_at": "2026-10-02T13:40:11Z",
"updated_at": "2026-11-19T10:02:55Z",
"previous_secret_expires_at": "2026-11-19T11:02:55Z",
"health": "healthy",
"secret": "whsec_Qm3v9Lx2cT8pZr5NbW1yKd7HsF4jGa6eUo0iXqCtVhE="
}
Enquanto previous_secret_expires_at não passar, o cabeçalho webhook-signature leva duas assinaturas v1, uma por segredo. Instale o segredo novo no receptor durante essa janela: o código acima aceita o pedido se qualquer uma das assinaturas coincidir.
Testar#
POST $BUSINESS_API/developer/webhooks/{id}/testenvia um eventowebhook.testsó para esse endpoint, pela fila normal, com assinatura e tentativas. Responde202com a entrega criada e409se o endpoint estiver desactivado ou em pausa.gotactl webhooks listen --forward-to http://localhost:3000/webhooksencaminha os eventos do sandbox para a sua máquina, assinados com um segredowhsec_gerado para a sessão e mostrado ao arrancar. Neste modo,webhook-idleva o ID do evento (wev_). A opção--eventslimita o encaminhamento a uma lista de tipos separados por vírgulas.gotactl events trigger invoice.paidgera um evento real no sandbox para acompanhar a verificação desde o envio até ao seu servidor.
Próximos passos#
- Tentativas e reenvios: o calendário de tentativas e quando uma entrega falha de vez.
- Testar webhooks: o envio de teste e o registo de entregas.
- Boas práticas: responder depressa e eliminar duplicados por
webhook-id. - Ouvir eventos com webhooks: criar o endpoint do princípio ao fim.