1. Prepare o endereço de recebimento
Um webhook é uma notificação enviada ao seu servidor quando ocorre um evento. O endereço cadastrado precisa estar acessível por HTTPS e aceitar o método e o formato descritos na documentação.
Configure a autenticação prevista na integração, valide os dados recebidos e não exponha credenciais em logs. Uma página que abre no navegador não prova que o endpoint aceita uma notificação.
2. Receba primeiro, processe com controle
Registre o evento com segurança antes de confirmar seu recebimento. Quando o processamento for demorado, use uma fila no seu sistema para não prender a resposta do endpoint.
Uma notificação pode ser reenviada. Use o identificador do evento ou um controle equivalente para que a mesma venda não gere duas entregas. Se houver dúvida sobre a sequência dos eventos, consulte o estado atual do pagamento.
3. Leia o erro de entrega
Um HTTP 404 costuma indicar que a rota não foi encontrada ou que o receptor não reconheceu o recurso. Um timeout indica que não houve resposta dentro do limite da chamada. Consulte também os logs do servidor que recebe o webhook.
Confira a URL cadastrada, o método aceito, as regras de autenticação e o tipo de evento. Um receptor preparado para pagamentos pode precisar de outro tratamento para eventos de saque.
4. Separe entrega da notificação e resultado financeiro
Falhar ao entregar um webhook não significa que a venda foi recusada. A cobrança pode ter sido paga enquanto o seu servidor estava indisponível.
Compare o estado da transação na API com o pedido e os registros de entrega. Corrija o receptor antes de planejar reprocessamentos, preservando o controle contra duplicidade.