> For AI agents: the complete documentation index is available at https://developers.orbita.nexxo.tec.br/llms.txt, the full documentation bundle is available at https://developers.orbita.nexxo.tec.br/llms-full.txt.

# Receber eventos por webhook

## Configure um receptor

Um administrador autorizado cadastra o webhook do projeto ou da organização. Use uma URL acessível pelo servidor e guarde o segredo retornado na criação. O cadastro pertence à API privada; uma API key pública não administra os webhooks.

O filtro `eventTypes` recebe nomes exatos de eventos separados por vírgula. Um filtro vazio assina todos os tipos. Confirme os tipos produzidos pela versão do backend do seu ambiente antes de restringir a assinatura.

## Headers recebidos

| Header              | Conteúdo                                                    |
| ------------------- | ----------------------------------------------------------- |
| `X-Nexxo-Delivery`  | UUID estável da entrega, inclusive entre tentativas.        |
| `X-Nexxo-Event`     | Tipo do evento.                                             |
| `X-Nexxo-Signature` | `sha256=` seguido do HMAC-SHA256 hexadecimal em minúsculas. |

A assinatura usa o segredo em UTF-8 e os bytes do corpo JSON enviado. Valide antes de fazer parse ou reserializar o JSON.

## Valide em Node.js

```javascript
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody, signature, secret) {
  if (!/^sha256=[a-f0-9]{64}$/.test(signature || '')) return false;
  const received = Buffer.from(signature.slice(7), 'hex');
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  return timingSafeEqual(received, expected);
}
```

`rawBody` deve ser o `Buffer` original recebido pelo servidor. Só depois de validar, faça `JSON.parse(rawBody.toString('utf8'))`.

## Processe com durabilidade

Verifique a assinatura, grave a entrega de forma durável e responda com `2xx`. Use uma chave única com o webhook/receptor e `X-Nexxo-Delivery` para que uma repetição não execute o efeito duas vezes. Conclua o trabalho demorado em segundo plano.

O worker atual faz até dez tentativas para falhas comuns, com espera progressiva. Restrições de acesso podem adiar a entrega separadamente. O destino pode aceitar um POST e a resposta se perder; por isso a deduplicação continua necessária.

O payload vem do evento de domínio. Não assuma que ele é igual ao DTO HTTP de uma issue nem que todos os eventos têm os mesmos campos.
