Incompatibilidade de assinatura
A causa mais comum é assinar JSON analisado em vez do corpo bruto exato ou usar um carimbo de data/hora diferente do cabeçalho da solicitação.
Testador de Webhooks
Teste seus WebhooksConfira a assinatura
Edite um corpo de exemplo e gere uma assinatura HMAC-SHA256 e uma requisição cURL para seu ambiente de teste.
01
Configure o teste
Informe o endereço, o segredo de teste e o timestamp.
A assinatura é calculada no navegador. Use um segredo de teste.
Timestamp Unix em milissegundos, como nos cabeçalhos do BoltUtil.
02
Edite o corpo e gere a assinatura
A assinatura e o cURL são atualizados ao editar o JSON.
Assinatura
HMAC-SHA256Informe um segredo, timestamp e JSON válidos.
Calculada com o timestamp, o corpo original e o segredo de teste.
JSON válido
cURL / POSTRequisição de teste
Informe um endereço, segredo, timestamp e JSON válidos.Exemplo de callback de pedido USDC, adaptável a USDT. Pedido, endereços e hash são fictícios e não comprovam pagamento.
A ferramenta não envia requisições. Execute o cURL manualmente no seu ambiente de teste.
Verificação
Verifique antes de continuar
Verifique com a mesma regra, registre o evento e atualize o pedido.
Ver guia de verificaçãoHMAC_SHA256(timestamp + "." + rawBody, secret)- 01
Verifique o corpo bruto
Use o carimbo de data/hora em milissegundos do cabeçalho e o corpo bruto exato para calcular o HMAC antes de analisar JSON. Espaços em branco, quebras de linha e ordem dos campos afetam a assinatura.
- 02
Use comparação segura de tempo
Compare a assinatura recebida com um auxiliar de tempo constante fornecido pelo tempo de execução da sua linguagem.
- 03
Grave com segurança e depois retorne 2xx
Somente retorne sucesso após registrar o evento ou colocá-lo em uma fila interna durável.
Diagnóstico de Webhooks
Por que um Webhook de pagamento pode falhar
A maioria dos problemas vem de verificação de assinatura, parsing do body, tratamento de retentativas ou retorno de sucesso antes de registrar o evento.
Segredo errado
Use o segredo do webhook configurado para o endpoint do comerciante. As chaves de API e os segredos do webhook devem ser tratados como credenciais diferentes.
O analisador de corpo alterou a carga útil
O middleware JSON pode reordenar ou reformatar cargas úteis. Capture o corpo bruto antes de analisar ao verificar assinaturas HMAC.
Endpoint retorna não-2xx
Respostas fora de 2xx indicam falha. Novas tentativas dependem do tipo de callback, status HTTP e política de retentativas.
O processamento não é idempotente
Elimine duplicatas por pedido e status ou ID único do evento. Um hash pode conter várias transferências.
Sucesso antes da durabilidade
Retorne HTTP 2xx somente após gravar o evento em seu banco de dados ou fila. Caso contrário, uma falha poderá causar a perda de uma notificação de pagamento concluída.
Perguntas frequentes
Perguntas de depuração Webhook
Use estas verificações quando o pagamento foi concluído mas sua aplicação não atualizou.
Por que minha verificação de assinatura do webhook falha?
Verifique o corpo exato da solicitação bruta, o cabeçalho do carimbo de data/hora e o segredo do webhook configurado. Assinar JSON analisado ou um corpo reformatado geralmente produz um HMAC diferente.
Meu endpoint do webhook deve retornar SUCCESS no corpo da resposta?
Não. BoltUtil usa o status HTTP: 2xx indica recebimento. Verifique e registre o evento antes de responder.
Como devo lidar com entregas duplicadas de webhook?
Use restrição única ou operação atômica por pedido e status ou ID do evento. Não use apenas o hash da transação.
Quando meu endpoint deve retornar HTTP 2xx?
Retorne 2xx após verificar e registrar o evento. Em caso de falha, retorne um erro adequado; retentativas dependem do callback e da política.