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

```javascript
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:

```http
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.

```bash
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}'
```

```json
{
  "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](/docs/webhooks/verify) para as versões em Python e Go, e [a visão geral dos webhooks](/docs/webhooks/overview) para as novas tentativas e os estados das entregas.

