# 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.

```javascript
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;
  });
}
```

```python
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())
```

```go
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
}
```

✓ Checkpoint: com o pedido de exemplo, o segredo acima e a janela de tempo desligada, a função devolve verdadeiro; basta mudar um carácter do corpo ou do `webhook-id` para devolver falso.

## 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

- [Tentativas e reenvios](/docs/webhooks/retries): o calendário de tentativas e quando uma entrega falha de vez.
- [Testar webhooks](/docs/webhooks/testing): o envio de teste e o registo de entregas.
- [Boas práticas](/docs/webhooks/best-practices): responder depressa e eliminar duplicados por `webhook-id`.
- [Ouvir eventos com webhooks](/docs/guides/listen-webhooks): criar o endpoint do princípio ao fim.

