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
- Abra Desenvolvedores › WebhooksNo ambiente certo: os endpoints de teste e de produção são cadastrados separadamente. Quem pode: Proprietário, Administrador ou Desenvolvedor.
- 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. - 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. - Envie um teste"Enviar teste" manda um
test.pingsó 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
- Confira a assinaturaCom o corpo cru, antes de ler o JSON. Veja Verificar X-Signature.
- DedupliquePelo
X-Event-Id(o mesmo que oiddo corpo): o mesmo evento pode chegar mais de uma vez. - 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.