# Verificar a assinatura

> Como confirmar que um webhook veio mesmo do Messajo, com exemplos em várias linguagens.

## Por que verificar

A URL do seu webhook é pública. Sem verificar a assinatura, qualquer um que descubra a URL pode mandar eventos falsos — uma "mensagem recebida" inventada, um "pagamento" que nunca aconteceu. A assinatura prova que o corpo veio do Messajo, com o seu segredo, e que não foi alterado no caminho. O horário dentro dela impede que alguém grave uma entrega e a repita depois.

## O cabeçalho

Cada entrega traz o cabeçalho `Messajo-Signature`:

```text
Messajo-Signature: t=1762697007,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

- `t` é o horário da assinatura, em segundos Unix. Aparece uma vez só.
- `v1` é o HMAC-SHA256 em hexadecimal. Durante a [rotação do segredo](#girar-o-segredo-sem-parar) vêm **dois** `v1`, um por segredo ativo: basta um bater.
- Ignore esquemas que você não conhece (um `v2=` futuro, por exemplo).

O segredo do destino começa com `whsec_` e aparece **uma vez só**, ao criar o destino (no painel ou na resposta de `POST /v1/destinations`). Depois o painel mostra só os 4 últimos caracteres. Perdeu? Gire o segredo.

## Passo a passo

1. Leia o **corpo cru** da requisição, exatamente os bytes que chegaram, **antes** de qualquer parse de JSON.
2. Separe `t` e os `v1` do cabeçalho.
3. Monte a mensagem `${t}.${corpo}` — o horário, um ponto e o corpo cru.
4. Calcule o HMAC-SHA256 dessa mensagem usando como chave o **segredo inteiro**, com o prefixo `whsec_`, em UTF-8. O resultado em hexadecimal minúsculo.
5. Compare com cada `v1` em **tempo constante** (`timingSafeEqual`, `hmac.compare_digest`, `hash_equals`). Comparação com `==` vaza informação pelo tempo de resposta.
6. Recuse se `t` estiver a mais de **5 minutos** do seu relógio, para trás ou para frente.

Assinatura inválida → responda `400` e descarte o evento. Válida → responda `2xx` rápido e processe depois (veja [Eventos](/webhooks/events/#ordem-e-duplicatas)).

## Exemplos

Os três exemplos não usam biblioteca externa e são testados a cada build contra o assinador do Messajo.

### Node.js

<Code code={nodeSnippet} lang="ts" title="verify.ts" />

### Python

<Code code={pythonSnippet} lang="python" title="verify.py" />

### PHP

<Code code={phpSnippet} lang="php" title="verify.php" />

Como pegar o corpo cru em cada framework:

| Framework | Corpo cru |
|---|---|
| Express | `app.post("/webhook", express.raw({ type: "application/json" }), …)` e `req.body.toString("utf8")` |
| Hono | `await c.req.text()` |
| FastAPI | `await request.body()` |
| Laravel | `$request->getContent()` |

Use o corpo cru na verificação e só depois faça o `JSON.parse` / `json.loads` / `json_decode`.

## n8n

1. No nó **Webhook**, em **Options**, ligue **Raw Body**.
2. Depois dele, um nó **Code** (JavaScript) com o código do exemplo Node.js, lendo o cabeçalho `messajo-signature` e o corpo cru do item recebido.
3. O nó Code só carrega `crypto` se o n8n permitir: defina `NODE_FUNCTION_ALLOW_BUILTIN=crypto` no ambiente do n8n e reinicie.
4. Assinatura inválida → pare o fluxo (nó **Stop and Error** ou um **IF**).

## Girar o segredo sem parar

1. No painel, abra o destino e clique em **Girar segredo**, ou chame `POST /v1/destinations/{id}/rotate-secret`. O Messajo gera um segredo novo e o mostra uma vez só.
2. Escolha a **janela de convivência**: de 0 a 72 horas, padrão **24 horas** (`keep_previous_hours` na API). Durante a janela os dois valem e cada entrega vem com dois `v1`, primeiro o do segredo novo, depois o do antigo:

   ```text
   Messajo-Signature: t=1762697007,v1=<hmac com o novo>,v1=<hmac com o antigo>
   ```

3. Troque o segredo na sua aplicação dentro da janela. Como basta um `v1` bater, não há momento em que eventos sejam recusados. O fim da janela aparece no destino (`previous_secret_expires_at` na API).
4. Passada a janela, o segredo antigo deixa de assinar e as entregas voltam a ter um `v1` só.

Com janela `0` o antigo para de assinar na hora: use só quando o segredo vazou. Girar de novo dentro da janela descarta o antigo anterior: valem só o segredo atual e o que acabou de ser substituído.

## Erros comuns

- **JSON re-serializado.** O framework fez parse do corpo e você assinou `JSON.stringify(req.body)`. Espaços, ordem de chaves e escape de acentos mudam e o HMAC não bate. Use o corpo cru.
- **Relógio errado.** Servidor sem NTP fica fora dos 5 minutos e recusa tudo como antigo. Sincronize o relógio.
- **Segredo com espaço.** Espaço ou quebra de linha no fim do segredo copiado (comum em `.env`). Confira o tamanho e remova espaços.
- **Segredo sem o prefixo.** A chave do HMAC é o segredo inteiro, **com** `whsec_`.
- **Corpo decodificado com outro charset.** Leia os bytes como UTF-8; acentos e emojis fazem diferença.
