Configurar endpoint

Cada mudança que importa (cobrança paga, pagamento concluído, devolução, MED) vira um evento, enviado por POST ao seu endpoint e assinado com o segredo dele. O endpoint se cadastra no painel; não há rota da API para isso.

Cadastrar

  1. Abra Desenvolvedores › WebhooksNo ambiente certo: os endpoints de teste e de produção são cadastrados separadamente. Quem pode: Proprietário, Administrador ou Desenvolvedor.
  2. Informe a URL e os grupos de eventosCobranças (charge.*), Pagamentos (payout.*), Devoluções (refund.*) e Infrações (MED) (dispute.*); todos vêm marcados. O endpoint recebe todos os eventos dos grupos escolhidos.
  3. Confirme com o app autenticador e copie o segredoO segredo whsec_… aparece uma única vez. Guarde numa variável de ambiente do servidor que recebe os eventos.
  4. Envie um teste"Enviar teste" manda um test.ping só para esse endpoint (até 10 por minuto). Ele não entra nos filtros: nenhum outro endpoint recebe.

Regras da URL

  • Só https, com endereço público. Endereços internos ou locais (localhost, redes privadas) e URL com usuário e senha são recusados no cadastro e conferidos de novo antes de cada entrega.
  • Redirecionamentos não são seguidos: um 301 ou 302 conta como falha. Cadastre a URL final.
  • Até 10 endpoints por ambiente.

Para receber no seu computador durante o desenvolvimento, exponha uma URL https pública que chegue até ele (um túnel, por exemplo).

Trocar o segredo

"Trocar segredo" no painel (com o app autenticador) vale na hora: as próximas entregas, inclusive as novas tentativas de eventos antigos, já saem assinadas com o segredo novo. Não há período com os dois valendo, então atualize o seu servidor logo em seguida; o que falhar nesse intervalo é tentado de novo.

Desativar e reenviar

  • Endpoint desativado não recebe os eventos que acontecem enquanto ele está desativado, nem depois de reativado.
  • No painel, cada entrega mostra as tentativas, o corpo enviado e a resposta do seu servidor. "Reenviar" manda de novo na hora.

O que o seu servidor faz

Para cada entrega

  1. Confira a assinaturaCom o corpo cru, antes de ler o JSON. Veja Verificar X-Signature.
  2. DedupliquePelo X-Event-Id (o mesmo que o id do corpo): o mesmo evento pode chegar mais de uma vez.
  3. Responda 2xx rápidoEm até 10 segundos. Guarde o evento e processe depois; qualquer outra resposta, ou demora, conta como falha e o evento volta.

Os tipos e o que cada um traz estão em Eventos; o calendário das novas tentativas, em Tentativas e cabeçalhos.