Testes

Testar é uma medida essencial ao colocar webhooks confiáveis e resilientes em produção. No entanto, testar webhooks pode ser uma experiência frustrante, principalmente se você não tiver as ferramentas certas.

Este guia cobre os problemas mais comuns de teste de webhooks e como o Hookdeck os resolve — de receber webhooks em localhost a reenviar eventos que falharam em produção. Para uma visão mais ampla dos tipos e metodologias de teste de webhooks (testes unitários, testes funcionais, testes de carga, profiling), veja o nosso guia completo de testes de webhooks. Para uma comparação de ferramentas de desenvolvimento local, veja as melhores ferramentas de teste de webhooks.

Por que testar webhooks é difícil?

Como depurar um webhook?

Depurar um webhook tem suas particularidades. Diferente do processo típico de depuração de software, em que você percorre o código da aplicação para encontrar erros de lógica, testar webhooks envolve mais coisas. Como um webhook transfere informação de uma aplicação para outra através da rede, o enlace de rede também entra no processo de depuração.

Você precisa acompanhar problemas de latência, falhas de rede, timeouts de rede e outros fatores para ter a visão completa do que pode ter causado a falha de um webhook.

Assim, depurar um webhook envolve acompanhar pelo menos estas 3 entidades:

• A origem do webhook (o produtor do webhook)
• O consumidor do webhook
• O enlace de rede entre o produtor e o consumidor do webhook

Além disso, webhooks só podem ser enviados para um endpoint HTTPS publicamente acessível. Isso adiciona uma camada extra de complexidade ao processo de teste e depuração.

Veja o nosso artigo “Complete Guide to Webhook Testing” para um detalhamento do passo a passo e das boas práticas de teste de webhooks.

Como (provavelmente) é a sua stack atual

Agora que você sabe o que envolve depurar um webhook, vamos ver como é uma configuração comum de teste de webhooks. Ela provavelmente é parecida com a que você usa hoje.

• O produtor do webhook (por exemplo, Stripe, GitHub ou Shopify)
• Um programa de tunelamento como o ngrok para receber seus webhooks durante o desenvolvimento local
• A sua aplicação hospedada (o consumidor do webhook)
• Um cliente HTTP como o Postman para enviar requisições à sua aplicação em produção com fins de teste

Essa stack com certeza resolve bastante coisa, mas ainda existem alguns buracos no fluxo de trabalho que podem não ser tão evidentes no começo. Vamos falar deles a seguir.

Limitações da sua stack atual

A stack descrita na seção anterior é boa para quem está preparado para testar e depurar webhooks visando confiabilidade, mas tem algumas limitações.

Primeiro, os produtores são independentes da sua infraestrutura, então você tem pouco ou nenhum controle sobre o que acontece do lado deles. O máximo que você pode fazer é acompanhar de perto as atividades de webhook do lado do produtor para observar como elas afetam a sua configuração.

Outra limitação está nas ferramentas de tunelamento usadas no desenvolvimento local com webhooks, como o ngrok. Embora essas ferramentas ofereçam alguma visibilidade que ajuda a depurar problemas durante o desenvolvimento, elas não podem ser usadas em ambientes de produção.

Quando um webhook falha em produção, uma ferramenta como o Postman pode ser usada para simular a requisição que falhou. Isso ajuda a depurar o webhook que realmente falhou e/ou a testar se a correção aplicada funcionou. O problema desse fluxo é que ele é manual e, portanto, sujeito a muitos erros. Também fica bastante trabalhoso conforme cresce a quantidade de webhooks com falha para reprocessar.

Ou seja, a configuração de teste descrita acima não escala em ambientes de produção e acaba desmoronando conforme o peso dos testes e da depuração aumenta.

Vamos agora ver os gargalos mais comuns nos testes de webhooks e como o Hookdeck ajuda a oferecer uma experiência de teste fluida tanto no ambiente local/de desenvolvimento quanto em produção.

Problemas de teste de webhooks e soluções com o Hookdeck

Você não consegue receber webhooks em localhost

Problema

Você precisa tunelar seus webhooks.

Solução

A ferramenta Hookdeck Online Test ajuda você a testar rapidamente o seu endpoint de webhook com uma conta real de um provedor como Shopify, Stripe, etc. Você também pode testar com um provedor fictício que simula qualquer um dos provedores de webhook mais comuns.

A ferramenta de teste permite que você informe o endpoint do seu servidor local/remoto e receba um endpoint HTTPS ativo e publicamente acessível como URL do seu webhook.

Depois disso, você pode testar os eventos de webhook e inspecionar os dados que vêm com eles.

A Hookdeck CLI ajuda você a contornar essas complexidades escutando os seus endpoints de webhook ativos e roteando as requisições para um endpoint de uma aplicação rodando no seu ambiente de desenvolvimento.

Webhooks precisam de um endpoint público e seguro para serem enviados. Isso significa que eles não podem ser recebidos diretamente no seu ambiente de desenvolvimento local.

Para contornar isso, você precisa de um software de proxy e tunelamento web. Esse software pega o tráfego (HTTPS) do seu webhook e o transporta até a sua máquina local.

Você precisa disparar um evento falso em um ambiente de desenvolvimento para testar

Problema

Você precisa de uma coleção de payloads.

Solução

Os bookmarks do Hookdeck resolvem esse problema dando a você a capacidade de marcar, etiquetar e reenviar os webhooks que te interessam, tudo sem recriar o evento no seu ambiente de produção.

Para testar o seu endpoint de webhook, você precisa simular eventos reais para gerar o webhook que será enviado ao endpoint. Rodar testes disparando eventos/webhooks em um ambiente de produção não é o ideal.

Uma forma de resolver isso é copiar manualmente o payload do webhook real e usar um cliente HTTP como o Postman para reenviar a requisição várias vezes durante o teste e o desenvolvimento.

Você não consegue reenviar um webhook

Problema

Você precisa reenviar um webhook.

Solução

O Hookdeck mantém um registro de todos os eventos e requisições de webhook e permite que você selecione e faça o retry de um webhook com um clique.

Retries automáticos não estão disponíveis em todos os provedores de webhook, o que dificulta reprocessar um webhook que falhou. Você também pode atingir o limite de retries automáticos permitido por um provedor.

O recomendado é manter um registro dos webhooks que chegam ao seu endpoint, para que você possa consultá-los caso precise reenviar um webhook que falhou. Os webhooks podem ser registrados em arquivos de log, tabelas de banco de dados ou sistemas de mensageria.

Você não consegue inspecionar o payload de um webhook

Problema

Você precisa registrar os webhooks em log.

Solução

O Hookdeck permite inspecionar o header, o body, o path, as queries e a resposta do servidor do evento de webhook.

Sem logs do lado do consumidor, informações do webhook como payload e headers ficam invisíveis.

É uma boa prática implementar logging no servidor que hospeda a aplicação consumidora de webhooks. Enquanto servidores como o NGINX já vêm com access logs ativados por padrão, um servidor como o Node.js exige que você mesmo implemente isso.

O Hookdeck registra todos os webhooks em log e oferece uma interface web interativa para você navegar pelos seus webhooks e inspecionar o payload de cada um.

Você não tem certeza se a sua correção funciona

Problema

Você precisa testar o seu endpoint de webhook.

Solução

O Hookdeck mantém um registro de todos os seus webhooks e oferece um botão Retry para reenviar manualmente uma requisição de webhook sem precisar recriar o evento no seu ambiente de produção. Assim você pode rodar o teste quantas vezes forem necessárias até confirmar que a sua correção funcionou.

Depois de aplicar uma correção no seu código, você precisa recriar o evento de webhook que falhou para confirmar que agora funciona. Disparar um evento real em um servidor de produção para esse teste não é o ideal e pode deixar a sua aplicação em um estado inconsistente.

A forma recomendada de fazer esse tipo de teste é usar um evento falso que tenha todos os atributos do evento original (payload, timestamps, headers, etc.) mas que não gere nenhum impacto na aplicação em produção.

Você esqueceu como trabalhar com um provedor

Problema

Você precisa do mesmo fluxo de trabalho para todos os provedores de webhook.

Solução

O Hookdeck é agnóstico de plataforma e entrega um fluxo de trabalho idêntico para cada provedor.

Discussão

O conhecimento sobre configurar webhooks em um provedor não se transfere diretamente para os outros. Isso acontece porque a forma de cada provedor lidar com webhooks é única e cada um traz o seu próprio conjunto de recursos.

Uma forma de harmonizar o seu fluxo de trabalho com webhooks é usar um API gateway que trate o webhook de cada provedor conforme suas particularidades. O gateway então oferece uma interface uniforme para interagir com o seu servidor de destino.

Exemplos de operações e atributos de webhook que podem ser harmonizados incluem autenticação, payload e políticas de retry, entre outros.

Você não sabe como solucionar problemas em cada provedor

Problema

Você precisa de um fluxo de trabalho unificado.

Solução

O Hookdeck conta com o recurso de Issues, que cria automaticamente um registro de issue quando um webhook de qualquer provedor falha e notifica o seu time. Você pode então abrir a issue e ver todas as informações necessárias para investigar o problema.

Uma vez corrigido o problema, você pode fazer o retry de todos os webhooks que falharam por causa dele e marcar a issue como resolvida.

Ao trabalhar com provedores diferentes, você precisa acompanhar os problemas que surgem em cada um e os passos para investigá-los. Além disso, o conhecimento sobre um problema específico em um provedor não se transfere diretamente para outro.

Conclusão

Testar webhooks de ponta a ponta significa contornar o fato de que você não consegue disparar payloads sob demanda com facilidade, não consegue expor o seu servidor local sem um túnel e não consegue reproduzir um caso extremo específico sem recriar as condições exatas que o causaram. Correlacionar logs entre o provedor, a sua infraestrutura e a sua aplicação é mais lento do que corrigir o bug em si, e reproduzir casos extremos localmente normalmente significa regerar eventos reais que você não consegue reenviar facilmente.

O Event Gateway do Hookdeck rastreia cada webhook recebido de ponta a ponta — requisição, payload, headers e resposta — e torna todo o histórico de entregas pesquisável e reenviável com um clique. A 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.

Para uma comparação de ferramentas de desenvolvimento local com webhooks, incluindo Hookdeck CLI, ngrok, localtunnel e outras, veja o nosso guia as melhores ferramentas de teste de webhooks para desenvolvimento local.