Guia completo de troubleshooting e debug de webhooks

Se o desenvolvimento de software existisse sem bugs, os desenvolvedores seriam as pessoas mais felizes do mundo. Não haveria mãos batendo no teclado de frustração, nem noites em que você acorda de repente porque um estalo no cérebro te disse "como consertar aquele bug". Infelizmente, esse luxo não existe: parte do desenvolvimento de software é remover bugs do código escrito, de forma iterativa, até que (quase) não sobre nenhum.

Ao desenvolver um software, uma boa parte do tempo é gasta testando e depurando o código para remover bugs, e desenvolver com webhooks não é exceção. Neste artigo, vamos falar sobre troubleshooting de webhooks. Passamos pelo que causa bugs no desenvolvimento com webhooks, como atacar esses bugs e quais ferramentas podem ajudar no processo de debug.

Teste e depure webhooks com o Hookdeck.

Inspecione payloads, reenvie eventos e desenvolva localmente com uma URL permanente — sem a dor de cabeça dos túneis.

Começar agora Saiba mais

Por que meus webhooks não estão funcionando?

Então, por que meus webhooks não estão funcionando?

Essa pergunta é bem parecida com aquela outra bem popular: por que meu código não está funcionando?

Os desenvolvedores perguntam muito isso porque há 90% de chance de o seu código não funcionar de primeira, e com webhooks é a mesma coisa. Esse obstáculo quase certamente vai aparecer e não é nenhum drama em si, mas é muito importante saber onde olhar quando os seus webhooks não estão se comportando como esperado.

Recebendo webhooks

A primeira coisa da qual você quer ter certeza é de que está recebendo os seus webhooks. Como webhooks são requisições HTTP comuns partindo de uma aplicação de origem para a sua API, eles podem falhar silenciosamente se não houver nada rastreando a requisição.

Você pode usar a ferramenta de teste online do Hookdeck para conferir se está recebendo os seus webhooks no endpoint esperado do seu servidor.

Uma coisa a fazer antes de trabalhar com webhooks é ler direito a documentação do provedor (não a documentação inteira, só a seção sobre webhooks) e olhar exemplos de código no site dele para dominar como consumir o webhook.

Outros passos que você pode dar:

Validação ao receber webhooks	Motivo
Faça um health check na origem do webhook	Às vezes (raramente), o sistema do seu provedor de webhooks está fora do ar e não está enviando webhooks. Boa parte dos provedores tem uma página de status que indica se o sistema está no ar ou não.
Verifique se o webhook aponta para o destino certo	Às vezes há um erro na URL do webhook informada, e os seus webhooks são enviados para o endpoint errado. Confira se você registrou a URL de webhook correta.
Certifique-se de que o servidor de destino está rodando	Você vai se surpreender com a quantidade de vezes em que acha que a sua API está no ar e ela não está. Além disso, se a requisição do webhook encontra um erro ao bater no seu endpoint (o código lança uma exceção), o seu sistema pode cair ou falhar silenciosamente, dando a impressão de que o webhook nunca chegou.

Requisitos do webhook

Outro motivo comum para os seus webhooks não funcionarem é você não estar cumprindo todos os requisitos para consumi-los. Já tive uma experiência em que recebia os webhooks, mas o corpo da requisição vinha vazio. Descobri que o meu servidor precisava fazer o parse do stream bruto da requisição. Esse é um dos motivos pelos quais você quer passar direito pela documentação do provedor. Como navegar pela documentação de webhooks é explicado em profundidade neste artigo.

Ainda assim, alguns requisitos gerais de webhooks são:

Requisito do webhook	Explicação
Assinatura do evento	Uma requisição de webhook é disparada por um evento que acontece no sistema de origem, então, antes de ter webhooks, você precisa estar inscrito em um evento.
URL do webhook	Os disparos de evento são enviados como requisição HTTP para um endpoint definido; garanta que o seu endpoint de destino foi informado corretamente.
HTTP seguro (HTTPS)	Se o seu servidor de destino não tem SSL instalado, você precisa instalar um ou usar um servidor proxy para terminação SSL.

O que depurar

Outro ponto de confusão no processo de debug é saber o que depurar. Como em qualquer processo de debug, depurar webhooks começa rastreando a origem do erro, lendo as mensagens de erro e interpretando essas mensagens para chegar à causa raiz e corrigi-la. Deixa eu compartilhar algumas dicas da minha experiência depurando webhooks.

Passo de debug	Verificação
O webhook foi recebido?	Como explicado antes, a primeira coisa da qual você quer ter certeza é de que a requisição chegou ao seu endpoint. Você pode tomar o caminho simples de inspecionar o objeto de requisição nos seus controllers imprimindo-o, ou usar um software como o Zipkin para tracing de requisições.
Ele vem da origem esperada?	Você não quer receber requisições de webhook da origem errada, então é preciso ter verificações para isso.
Ele contém a informação esperada?	A maioria das requisições de webhook traz no payload informações críticas para o trabalho que você quer fazer no seu servidor. Garanta que essa informação está presente nos webhooks que você recebe.
Você está validando a informação de que precisa?	Já tive um caso em que um valor booleano foi enviado em formato de string. Meu código tentava usar essa variável como booleano, e isso gerou bugs. Então, garanta que você está validando os tipos de dado que recebe e transformando-os quando necessário.
O webhook é do evento esperado?	Esse é outro erro humano que se infiltra facilmente no seu setup. Por exemplo, você achou que cadastrou um endpoint para um evento de conta atualizada, mas, por um motivo ou outro, cadastrou para um evento de conta criada. Esse erro simples pode gerar horas de troubleshooting inútil. Faça as verificações adequadas; alguns provedores são gentis o suficiente para incluir o tipo do evento em um header ou no corpo da requisição.
A sua API respondeu adequadamente?	Isso é específico de como cada aplicação responde ao webhook que assina. Garanta que você está processando o webhook adequadamente e retornando o código de status correto.
O processamento é idempotente?	Idempotência é coisa séria com webhooks, já que você quer evitar processamento duplicado quando um webhook dispara mais de uma vez.
A autenticação é obrigatória?	Às vezes os seus webhooks são recusados porque você não está cumprindo os requisitos de autenticação deles. Garanta que você está tratando isso adequadamente. Informações sobre como autenticar webhooks costumam estar no site do provedor.

Uma das formas de responder rapidamente às perguntas acima é usar a ferramenta online de teste de webhooks do Hookdeck para testar o seu endpoint em desenvolvimento ou produção.

Por que depurar webhooks pode ser difícil

Vamos encarar: depurar pode ser bem difícil. Depurar webhooks é ainda mais difícil, porque envolve tanto a camada de rede (as requisições HTTP dos webhooks) quanto a de aplicação (o seu código). Vamos passar por alguns motivos que fazem o debug de webhooks ficar frustrante rapidinho.

Reproduzir o erro no ambiente local

Quando um erro acontece, o primeiro passo é recriá-lo para inspecioná-lo em um ambiente isolado. Fazer isso com webhooks é bem difícil, porque você precisa simular tanto as condições do provedor do webhook (por exemplo, Stripe, Shopify etc.) quanto as condições no seu endpoint em que o webhook foi recebido. Por exemplo, ao tentar depurar meus webhooks da Shopify em produção, preciso criar uma nova loja Shopify de desenvolvimento e recriar o cenário que causou o erro em produção. Imagine tentar replicar esse mesmo cenário em uma conta de teste para uma loja que tem dados de produção. Para complicar, o trial gratuito da Shopify expira em 14 dias, então você tem que pagar para manter uma loja de desenvolvimento ou criar uma nova do zero. Lembre que o seu setup de debug também precisa ser feito no ambiente local para se manter isolado, o que torna ainda mais difícil recriar o erro.

Trabalhar em localhost

Ao recriar o seu erro localmente, você só consegue subir ambientes de servidor em localhost. Esses servidores não são acessíveis publicamente e, por isso, o seu provedor de webhooks não consegue alcançá-los. Isso adiciona uma etapa extra ao processo de debug para contornar firewalls e NATs e tornar o servidor local acessível publicamente. Lembre que você precisa dar acesso ao seu servidor por HTTPS.

Para superar tudo isso e conseguir receber e testar os seus webhooks em localhost, você pode usar a ferramenta de teste de webhooks do Hookdeck.

Idempotência ao enviar dados fictícios

Dados fictícios são bastante usados em debug, e uma característica deles é que sempre produzem o mesmo resultado. Imagine que o seu teste cria um novo usuário único no banco de dados; isso significa que, toda vez que você rodar o teste, precisa limpar o usuário do banco antes de rodar outro. Isso pode ficar frustrante se não for automatizado. Às vezes os desenvolvedores comentam a lógica que torna o processamento idempotente só para conseguir rodar vários testes. Essa é uma prática ruim, já que bugs podem ser introduzidos no processo ou você pode esquecer de descomentar o código, comprometendo a integridade da sua aplicação.

O que você precisa para depurar webhooks

Esperamos que este artigo não tenha te assustado a ponto de achar que depurar webhooks é uma tarefa impossível. Não entre em pânico: existem ferramentas para tudo o que foi mencionado acima. Mas, antes de chegarmos nelas, vamos ver algumas coisas de que você vai precisar para começar a depurar webhooks.

Requisito para depurar webhooks	Explicação
URL do webhook	Você precisa conseguir gerar uma URL de webhook publicamente acessível, por HTTPS, para o endpoint da sua aplicação.
Teste de webhook	Você precisa subir o seu servidor localmente e mantê-lo rodando com o código adequado para depurar o processo.
Ferramentas de inspeção	O seu setup de debug precisa ter ferramentas para inspecionar a requisição do webhook. Isso pode ser feito com as ferramentas de debug da sua IDE (definindo breakpoints para inspecionar a requisição) ou com ferramentas especializadas, com dashboards para visualizar o objeto de requisição.

Ferramentas para depurar webhooks

Agora que você entende bem o processo de debug de webhooks, vamos ver as ferramentas construídas para isso.

Ferramenta de teste de webhooks do Hookdeck

O Hookdeck Console é uma ferramenta online de teste para validar o comportamento dos seus webhooks. Ela permite usar URLs de webhook locais e remotas e testá-las com webhooks do seu provedor real ou de um provedor simulado. Assim, você supera todas as inconveniências de rodar testes em um webhook durante o desenvolvimento.

Hookdeck CLI

O Hookdeck CLI combina a capacidade de gerar uma URL de webhook publicamente acessível e persistente para o seu endpoint com um dashboard de inspeção para ler os detalhes das suas requisições de webhook.

Ele pode ser instalado e configurado em todos os sistemas operacionais, e é gratuito.

Ngrok

O Ngrok é uma ferramenta open source que expõe à internet pública, por meio de túneis seguros, servidores locais escondidos atrás de NATs e firewalls. O Ngrok facilita gerar rapidamente uma URL segura para usar como URL de webhook. Ele também inclui um dashboard simples para monitorar as requisições que chegam ao seu endpoint.

Você pode saber mais sobre o Ngrok e como configurá-lo no site deles. Também vale conferir o nosso guia de debug usando Ngrok.

RequestBin

O RequestBin é um serviço gratuito da Pipedream que permite capturar, interpretar e inspecionar requisições HTTP. Com o RequestBin, você sobe uma URL publicamente acessível com o clique de um botão e aponta as suas requisições de webhook direto para ela.

Quando uma requisição chega ao seu endpoint, o RequestBin te dá clareza sobre o objeto de requisição para inspeção. O RequestBin também oferece endpoints privados e upload de arquivos. Você pode saber mais sobre o RequestBin no site oficial.

Como o Hookdeck ajuda

Depurar uma entrega de webhook que falhou normalmente significa caçar logs em sistemas que não compartilham IDs de requisição, timestamps nem formatos — e, quando você termina de correlacionar tudo, a correção em si é a parte fácil. Correlacionar logs entre o provedor, a sua infraestrutura e a sua aplicação é mais lento do que corrigir o bug de verdade, e reproduzir casos de borda localmente costuma exigir regerar eventos reais que você não consegue reenviar com facilidade.

O Event Gateway do Hookdeck rastreia cada webhook de entrada ponta a ponta (requisição, payload, headers e resposta) e torna cada entrega histórica pesquisável e reenviável com um clique. O Hookdeck CLI te dá uma URL permanente de desenvolvimento local que não muda entre sessões, e qualquer evento passado pode ser reenviado para o seu servidor local sem envolver o provedor.

Tipos de teste Guia de troubleshooting