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ídodossie.partial— concluído com pendênciasdossie.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ínculosupplier.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
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:
- Implementar um endpoint HTTPS que responda ao desafio de verificação e valide a assinatura;
- publicá-lo num endereço acessível pela internet;
- cadastrá-lo e clicar em Verificar.
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.
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.
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 |