Como corrigir webhooks de pagamento cripto atrasados

Como corrigir um webhook de pagamento em criptomoedas que chega atrasado

Um webhook atrasado é irritante porque parece algo simples, mas raramente é. O pagamento pode estar certo, o webhook também, e mesmo assim seu app pode continuar mostrando “aguardando” por 12 minutos. Para entender essa diferença e descobrir como corrigir webhook de pagamento em criptomoedas atrasado, você precisa de horários registrados, não de suposições.

Comece comparando quatro horários do mesmo evento: quando ele foi criado, quando o provedor o enviou, quando seu servidor o recebeu e quando sua aplicação o processou. Se você olhar apenas o último, não terá como saber o que aconteceu. Se o evento foi criado às 10:01, enviado às 10:02, recebido às 10:02:04 e processado às 10:08, o atraso não está na entrega do provedor. Está do seu lado.

Essa diferença importa nos pagamentos em criptomoedas, em que um único pagamento pode passar por eventos na blockchain, verificações do provedor e atualizações internas do pedido. Um webhook que chega atrasado pode significar que a blockchain estava lenta, que a plataforma de pagamento aguardou confirmações ou que sua própria fila ficou congestionada. São três problemas diferentes, cada um com sua solução. Trate-os separadamente.

Se você também precisa entender como as escolhas de configuração afetam o comportamento da entrega, nosso guia sobre gateways de pagamento em criptomoedas para ecommerce aborda o lado do gateway sem se perder em detalhes desnecessários de implementação.

1. Confirme o atraso comparando os horários dos dois lados

Abra um evento e anote todos os horários em um só lugar. Consulte o registro do evento no provedor, os logs de entrada da sua infraestrutura e a primeira linha do log do seu handler. Três registros podem contar a história com clareza. Quatro são ainda melhores.

Há três pontos em que o atraso pode ocorrer. Primeiro, o evento da blockchain pode ainda não estar finalizado. Segundo, o provedor pode ter esperado antes de enviar o webhook. Terceiro, sua aplicação pode ter recebido o webhook, mas só o processado mais tarde. Esse último caso costuma enganar as equipes, porque, à primeira vista, a solicitação parece ter sido bem-sucedida.

Não confie apenas no horário de recebimento. Uma solicitação pode chegar à borda da sua infraestrutura às 14:20 e ficar na fila até as 14:27, antes de o código começar a executá-la. Isso não é um webhook atrasado pelo provedor. É um atraso na sua própria cadeia de processamento.

Uma dica prática: compare o ID do evento do provedor com o ID do pedido e registre os dois na mesma entrada do log. Um webhook atrasado que chega ao pedido correto continua atrasado, mas pelo menos você consegue provar em que ponto o atraso começa. Isso pode poupar horas.

2. Verifique se o atraso está na fila do seu endpoint, e não no provedor

Um webhook pode chegar pontualmente à sua infraestrutura e ainda assim parecer atrasado se o endpoint for lento. O processamento demorado da solicitação é o suspeito mais comum. Esgotamento de threads, pool de workers saturado, acúmulo de tarefas em segundo plano, buffering no proxy reverso e inicializações a frio em funções serverless também podem causar o problema. Muitas vezes, um desses cinco fatores é o verdadeiro culpado.

Pense em um endpoint de checkout que também verifica o estoque, registra dados de análise, envia um email e atualiza o saldo de uma carteira antes de responder com o código 200. Esse modelo pode funcionar em um dia tranquilo. Sob carga, porém, cria uma fila. O webhook não está atrasado na entrada; está esperando no corredor.

Veja quanto tempo a conexão HTTP fica aberta. Se o provedor enviou o webhook às 09:12 e seu app registra “processado” às 09:19, inspecione o caminho exato. Um proxy reverso pode estar armazenando o corpo em buffer. Um worker pode estar bloqueado por outra tarefa. Uma função serverless pode ter passado 4 segundos inicializando. Esses números mudam o diagnóstico.

Handlers curtos ajudam. Quanto mais curtos, melhor. É fácil encaminhar para outra fila uma solicitação respondida em menos de 200 ms. Já um handler que executa oito etapas antes de responder não é nada fácil de gerenciar.

3. Analise as tentativas de reenvio e os timeouts para encontrar atrasos ocultos

Alguns webhooks que parecem “atrasados” são, na verdade, consequência de novas tentativas. Se seu endpoint atinge o timeout, retorna um status diferente de 2xx ou demora muito para encerrar a conexão, o provedor pode tentar novamente mais tarde. Aí você vê o mesmo evento de novo, e a tentativa posterior é processada. Isso cria a impressão de atraso.

Confira as configurações de timeout dos dois lados. Seu app pode permitir 15 segundos, enquanto o provedor espera uma resposta em 5. Ou o proxy pode encerrar a conexão aos 10 segundos, enquanto seu app continua trabalhando até os 12. Esses limites incompatíveis fazem os problemas de tempo parecerem aleatórios. Mas não são.

Revise os códigos de resposta de um evento atrasado. Um 500, 502, 504 ou até uma longa espera antes de um 200 pode provocar uma segunda entrega. Se essa segunda tentativa chegar 6 minutos depois, a atualização do pedido parecerá “atrasada”, mas é provável que a primeira tentativa tenha falhado sem deixar sinais claros.

Para equipes que estão testando esses casos extremos, como testar um pagamento em criptomoedas é uma boa leitura complementar antes de fazer qualquer alteração em produção.

4. Verifique a latência da rede e da infraestrutura no caminho da entrega

Meça o caminho inteiro, não apenas o seu código. A consulta DNS, o handshake TLS, o comportamento da CDN, a inspeção do WAF, os saltos entre proxies e a distância entre regiões podem atrasar a solicitação antes mesmo de o webhook chegar ao handler. Um único salto raramente faz muita diferença. Cinco já podem fazer.

Um provedor em uma região e um app em outra podem estar separados por 90 ms, 200 ms ou mais em cada solicitação. Parece pouco, até que um webhook seja enviado durante um pico de tráfego e a conexão fique instável. Aí, 200 ms viram 2 segundos, e 2 segundos viram um chamado para o suporte.

Fique de olho no buffering na CDN ou na camada de borda. Algumas configurações esperam a leitura do corpo inteiro da solicitação antes de encaminhá-la. Outras inspecionam o payload primeiro. Se o payload do webhook for pequeno, talvez isso não faça diferença. Mas, se a borda estiver sobrecarregada, o webhook vai esperar de qualquer forma.

Um teste direto pode ajudar: envie uma solicitação conhecida a partir da mesma região do provedor e compare o horário de chegada com o do webhook em produção. Se a solicitação de teste chega em 40 ms e o webhook demora 2 segundos, a rede provavelmente não é o único problema. O restante está dentro da sua infraestrutura.

5. Diferencie o atraso na finalização do evento do atraso na entrega do webhook

Os sistemas de pagamento em criptomoedas muitas vezes aguardam confirmações antes de emitir o webhook. Isso é intencional. Uma transação pode aparecer na blockchain antes de ser seguro marcá-la como finalizada. O risco de reorganização da cadeia, as etapas internas de liquidação e as verificações de políticas podem atrasar o webhook de propósito.

É aqui que as equipes confundem dois tipos de atraso. Um pagamento pode entrar na blockchain às 15:00, mas o provedor espera uma, duas ou seis confirmações antes de enviar o status final. Nesse caso, o webhook não está atrasado. Ele está fazendo exatamente o que a regra de negócio determina.

Faça uma pergunta simples: esse webhook deve ser disparado no momento da transmissão, após a primeira confirmação ou só na liquidação final? Se ninguém consegue responder em uma frase, o sistema já está vago demais. E sistemas vagos geram chamados de suporte às três da manhã.

Para lojistas que estão comparando opções de implementação, um gateway de pagamento em criptomoedas para freelancers também pode ajudar a entender o momento em que o status de pagamento muda em faturas e atualizações parciais.

6. Verifique a lógica de agrupamento, debounce ou agregação da plataforma de pagamento

Algumas plataformas retêm eventos de propósito. Elas agrupam mudanças de status, aplicam debounce a atualizações frequentes ou combinam vários sinais de baixo nível em um webhook mais simples. Isso pode ser uma boa escolha de arquitetura. Também pode explicar por que um webhook chega 4 minutos depois do evento que o originou.

Procure regras como “enviar apenas o status final”, “agrupar alterações durante uma janela de 30 segundos” ou “aguardar a concordância entre a blockchain e o razão interno”. Essas políticas reduzem o volume de notificações. Também causam atrasos de propósito. Se o seu app espera notificações imediatas de cada evento, a política vai parecer defeituosa, mesmo quando está funcionando como deveria.

Não presuma que mais webhooks são sempre melhores. Uma plataforma que envia seis atualizações para um único pagamento pode gerar ruído. Outra que envia uma só após consolidar as informações pode causar demora. A escolha certa depende do que o fluxo do seu pedido precisa e de quanta incerteza você pode tolerar antes de preparar o pedido.

Se você precisa de um modelo para medir o desempenho do lado do pagamento, como medir o sucesso dos pagamentos em criptomoedas é útil, pois as métricas de atraso e de sucesso costumam usar o mesmo histórico de eventos.

7. Adicione observabilidade para localizar o início do atraso

Para entender por que meu webhook de pagamento cripto demora para chegar e aprender como diagnosticar atraso em webhook de pagamento, registre o ID do evento do provedor, o horário de chegada da solicitação, o horário da resposta, o início do processamento e o tempo na fila. Esses cinco campos são suficientes para revelar a maioria dos problemas com webhooks atrasados. Sem eles, qualquer atraso vira motivo de discussão.

Use uma linha de log por evento, em vez de três registros que mal correspondem entre si. Se a solicitação chega às 11:14:02, o handler começa às 11:14:07 e o processamento na fila começa às 11:14:11, você já sabe que o atraso é interno. Se a própria chegada também ocorre tarde, o problema está em um ponto anterior do fluxo. Com logs claros, isso fica evidente.

Além disso, acompanhe as tentativas de reenvio pelo ID do evento. Se um webhook atrasado chega duas vezes, isso pode mostrar se a primeira tentativa foi aceita, rejeitada ou simplesmente atrasada pela sua infraestrutura. Isso é útil quando o provedor afirma que o evento foi “entregue”, pois entrega não é o mesmo que processamento.

Configure também um alerta para a diferença entre o recebimento e o processamento. Uma diferença de 10 segundos pode ser normal em um sistema e desastrosa em outro. Defina o limite de acordo com o seu próprio SLA, não com uma publicação qualquer na internet.

Uma observação rápida: um registro de data e hora sem fuso horário é uma armadilha. Parece organizado, mas acaba causando problemas.

8. Defina uma alternativa segura para atualizações tardias do status do pagamento

Até um webhook bem ajustado pode chegar atrasado. Seu app ainda precisa de um plano alternativo. Uma rotina de reconciliação, uma verificação periódica ou um processo de revisão manual podem manter o status do pedido correto quando o webhook não cumpre o SLA normal. Isso não é apenas um plano de contingência; faz parte da arquitetura.

Escolha uma alternativa e defina os limites. Por exemplo: se não houver webhook para um pagamento após 5 minutos, encaminhe-o para reconciliação. Se nenhuma atualização de liquidação chegar dentro do prazo definido, consulte o provedor ou o estado da blockchain. Se ainda não for possível verificar o pagamento, encaminhe-o para revisão manual. É uma sequência simples, e simplicidade é uma vantagem nesse caso.

Não deixe atualizações de status atrasadas paradas em “pendente”, sem qualquer aviso. Isso cria falsas expectativas para o cliente e uma falsa sensação de segurança para o suporte. Um webhook atrasado pode ser inofensivo. Vinte sem qualquer alerta podem comprometer todo o fluxo de pedidos.

Se sua equipe também está deixando de fazer o processamento manual, como migrar dos pagamentos manuais em criptomoedas mostra por que é importante ter uma alternativa quando o status do pagamento chega depois do momento previsto pelo fluxo normal.

Se o atraso ocorre apenas em algumas rotas, comece comparando as regiões e a infraestrutura. Se acontece em todas, compare a duração do handler, o tempo na fila e o comportamento das novas tentativas. Se o padrão depende do número de confirmações, a causa é a política da blockchain. Essa é a diferença entre um erro e uma regra.

Mais um detalhe: mantenha no ambiente de homologação um evento de teste com um ID conhecido e um ID de pedido fixo. Execute-o após cada alteração em proxies, filas ou configurações de novas tentativas. Um único teste pode revelar um atraso que, de outra forma, passaria despercebido por semanas.