Configurar um endpoint
1. Implemente o desafio antes de cadastrar
Quando você clica em Verificar, nós fazemos um POST no seu endereço:
Code
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:
Code
⚠️ 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
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, a rotação acontece sem nenhuma entrega perdida.