# Configurar um endpoint

## 1. Implemente o desafio **antes** de cadastrar

Quando você clica em **Verificar**, nós fazemos um `POST` no seu endereço:

```http
POST /seu-endpoint
Content-Type: application/json
X-AutoConsulta-Event-Type: webhook.verification

{"type":"webhook.verification","challenge":"<um token>"}
```

:::note
Este pedido **não é assinado**, e isso é proposital: no momento do desafio você ainda não provou
ser dono do endereço, então ainda não há segredo estabelecido entre nós. **Não tente validar
assinatura aqui** — você recusaria o próprio desafio e nunca conseguiria verificar.
:::

Seu endpoint tem de **devolver o mesmo `challenge`**. Qualquer uma das três formas serve:

```js
// corpo JSON  (a mais comum)
res.status(200).json({ challenge: body.challenge })

// ou corpo cru
res.status(200).send(body.challenge)

// ou header
res.setHeader('X-AutoConsulta-Challenge', body.challenge).status(200).end()
```

⚠️ **Não redirecione.** Não seguimos redirecionamentos no desafio. Se `A` redireciona para `B` e o
`B` ecoa o token, teríamos verificado o `B` e passaríamos a entregar no `A` — uma verificação que
mente é pior que nenhuma. **O endereço que responde tem de ser o endereço cadastrado.**

## 2. Publique

O endereço precisa ser **HTTPS** e alcançável pela internet. Recusamos endereços que apontem para
redes internas, e isso não é configurável — é o que impede que nosso tráfego seja usado contra um
terceiro que nunca consentiu em recebê-lo.

## 3. Cadastre e verifique

Em **Configurações → Webhooks**, informe a URL e escolha os eventos. Depois clique em **Verificar**.

⚠️ A tela oferece hoje apenas os eventos de **dossiê**. Os três do **canal de certificação**
(`client.activated`, `supplier.status_changed`, `supplier.seal_expiring`) são habilitados por nós a
pedido, no mesmo endereço já verificado — nada muda no desafio nem na assinatura.

Dá certo na primeira se o passo 1 estiver pronto. Se falhar, corrija o endpoint **antes** de tentar
de novo — as tentativas são contadas.

## 4. Guarde o segredo

O cadastro gera um segredo (`whsec_…`). É com ele que você [confere a assinatura](/webhooks/verificar-assinatura)
de cada entrega.

Ele aparece uma vez na criação; depois disso só pela ação **Revelar**, na mesma tela. Guarde-o onde
você guarda credencial — não no código.

## Depois

**Trocar a URL derruba a verificação.** Editar o endereço zera o estado verificado e desativa o
endpoint: o consentimento foi dado para *aquele* endereço, não para o serviço atrás dele. Depois de
trocar, verifique de novo.

**Desativar** interrompe as entregas sem apagar o cadastro.

## Rotação do segredo

Ao rotacionar, os **dois** segredos valem por **24 horas**. Nessa janela, cada entrega chega com
duas assinaturas — a nova primeiro. Se o seu código [testa as duas](/webhooks/verificar-assinatura),
a rotação acontece sem nenhuma entrega perdida.