# O que são webhooks

Coisas que acontecem do nosso lado — um resultado que fica pronto, uma certificação que muda de
estado — têm dois caminhos até o seu sistema. Você pode **perguntar**, chamando a rota de leitura de
tempos em tempos; ou pode **ser avisado**: registrar um endereço seu e receber uma requisição nossa
no momento em que aquilo acontece.

O segundo caminho são os webhooks.

## Quando vale a pena

| situação | caminho |
| --- | --- |
| poucas consultas, resultado logo em seguida | `GET /status` |
| volume, ou resultado que demora | **webhook** |
| seu sistema não pode ficar consultando | **webhook** |
| acompanhar a certificação dos fornecedores de um canal | **webhook** (ou varredura periódica da lista) |

Não é obrigatório. As rotas de leitura continuam funcionando e **não cobram** — `GET /status` para o
resultado de uma consulta, `GET /distributor/clients/{id}/suppliers` para o estado dos fornecedores.

## O que você recebe

Um `POST` no seu endereço, com o conteúdo no corpo, **assinado**. São **seis** eventos, em duas
famílias — e você assina só os que interessam.

### Dossiê — o resultado ficou pronto

- `dossie.completed` — concluído
- `dossie.partial` — concluído com pendências
- `dossie.failed` — falhou

### Canal de certificação — algo mudou de estado

Estes só interessam a quem opera um **canal de distribuição** (certifica os fornecedores dos seus
clientes). Se você não tem canal, ignore-os: eles nunca vão chegar.

- `client.activated` — um cliente seu concluiu o primeiro acesso e autorizou o vínculo
- `supplier.status_changed` — um fornecedor mudou de estado (do convite ao selo vencido)
- `supplier.seal_expiring` — o selo de um fornecedor vence em 10, 7 ou 3 dias

:::note[O que os eventos do canal NÃO dizem]
Um `supplier.status_changed` conta **que** a certificação chegou àquele estado — inclusive quando
ela **não** se conclui. Ele nunca diz **por quê**: não há motivo, etapa, checagem que falhou nem
decisão em nenhum campo. O andamento é de quem intermedia; o conteúdo é do fornecedor.
:::

## O que isso exige de você

Webhook não é uma caixa que se marca: é um endereço **seu** que precisa saber receber. Em ordem:

1. **Implementar** um endpoint HTTPS que responda ao desafio de verificação e valide a assinatura;
2. **publicá-lo** num endereço acessível pela internet;
3. **cadastrá-lo** e clicar em Verificar.

:::note[Eventos do canal: peça a habilitação]
A tela de cadastro oferece hoje apenas os eventos de **dossiê**. Para receber os três do **canal de
certificação**, cadastre o endereço normalmente e peça a habilitação — nós marcamos os eventos na
sua conta. Tudo o mais (desafio, assinatura, retentativa) é idêntico.
:::

:::caution[A ordem importa, e errá-la trava você por uma hora]
São **5 tentativas de verificação por hora** por endpoint (e 10 por conta). Se você cadastrar e
ficar clicando em Verificar antes de o endpoint saber responder, esgota as tentativas e fica
esperando a janela virar.

**Implemente primeiro. Verifique depois.**
:::

Comece por [Configurar um endpoint](/webhooks/configurar).

## Limites

| | |
| --- | --- |
| endpoints por conta | 3 |
| tentativas de verificação | 5/hora por endpoint · 10/hora por conta |
| validade do token de verificação | 30 minutos |
| tempo limite de cada entrega | 10 segundos |