PT EN

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:

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

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.

bash
curl -X POST $BUSINESS_API/developer/webhooks/whk_2pR7tLx4NcQ9bV3mKw8ZsYe1HdF/roll \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overlap_seconds": 3600}'
json
{
  "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}/test envia um evento webhook.test só para esse endpoint, pela fila normal, com assinatura e tentativas. Responde 202 com a entrega criada e 409 se o endpoint estiver desactivado ou em pausa.
  • gotactl webhooks listen --forward-to http://localhost:3000/webhooks encaminha os eventos do sandbox para a sua máquina, assinados com um segredo whsec_ gerado para a sessão e mostrado ao arrancar. Neste modo, webhook-id leva o ID do evento (wev_). A opção --events limita o encaminhamento a uma lista de tipos separados por vírgulas.
  • gotactl events trigger invoice.paid gera um evento real no sandbox para acompanhar a verificação desde o envio até ao seu servidor.

Próximos passos#