Tutorial: como configurar um webhook

Há três perguntas importantes que se destacam ao aprender uma nova tecnologia: o what, o why e o how. Em um artigo anterior, analisamos a fundo o que são webhooks e por que você precisa deles. Neste tutorial, vamos ao how.

Antes de começar, deixe-me compartilhar algumas dicas úteis sobre leitura de documentação que descobri ao longo dos anos trabalhando com webhooks. Já passei por bastante frustração tentando encontrar a informação certa na documentação de webhooks de diferentes provedores.

Dicas para ler documentação de webhooks

Percorrer documentação técnica não costuma ser uma atividade divertida para a maioria das pessoas desenvolvedoras, e a documentação de provedores de webhooks não é exceção.

Tutorial: como configurar webhooks da Stripe

Agora que temos uma boa base sobre webhooks, vamos colocar esse conhecimento em prática com um exercício usando a Stripe. Vamos criar uma conta na Stripe e registrar webhooks para receber requisições em um servidor Node.js de demonstração.

Se quiser saber mais sobre os webhooks da Stripe antes de começar, você pode ler a documentação em Developer Tools → Webhooks. Ali você encontra informações sobre

1. Como trabalhar com diferentes linguagens de programação
2. Assinaturas de verificação da Stripe para autenticação
3. Boas práticas de integração de webhooks da Stripe
4. Exemplos de integração

Crie uma conta na Stripe

Acesse a página de registro da Stripe para criar uma nova conta. Você precisará verificar o seu endereço de e-mail depois do cadastro.

Clone uma API Node.js

Com a conta na Stripe criada, o próximo passo é clonar a API Node.js de demonstração. A API que vamos usar está disponível no repositório da Hookdeck no GitHub. Clone esse repositório executando o comando a seguir:

git clone https://github.com/hookdeck/nodejs-webhook-server-example.git

Isso deixará o projeto disponível no local do seu sistema de arquivos onde você executou o comando.

Navegue até a raiz do projeto e instale as dependências necessárias executando os seguintes comandos:

cd nodejs-webhook-server-example
npm install

Quando a instalação terminar, você pode rodar o servidor Node.js com o comando:

npm start

Isso vai inicializar a aplicação e imprimir na tela uma mensagem indicando que a API está rodando e escutando conexões na port 1337.

O endpoint usado para as requisições de webhook é /stripe-webhooks-endpoint e pode ser encontrado no arquivo src/routes.ts, como mostrado abaixo:

router.post(
  "/stripe-webhooks-endpoint",
  bodyParser.raw({ type: "application/json" }),
  function (req, res) {
    console.log(req.body);
    res.send("Stripe Successfully received Webhook request");
  },
);

Esse endpoint recebe as requisições de webhook, imprime o corpo da requisição no console e retorna uma mensagem.

Obtenha uma URL de webhook

Para que a aplicação de origem envie uma requisição de webhook, a aplicação de destino precisa registrar uma URL de webhook na origem. A maioria dos provedores também exige que esse endpoint use o protocolo HTTPS por questões de segurança. Precisamos, portanto, de uma URL publicamente acessível que use HTTPS.

Obtenha uma URL de webhook com a ferramenta de teste da Hookdeck:

Você também pode obter uma URL de webhook usando a CLI da Hookdeck. Com ela, você recebe webhooks localmente e os depura sem atrito. Acesse a documentação da CLI para instalar e configurar a ferramenta no seu sistema operacional.

Concluída a configuração, o próximo passo é usar a CLI para gerar uma URL de webhook que aponte para a aplicação em execução. Para isso, execute o comando:

hookdeck listen 1337

Esse comando inicia uma sessão interativa em que a CLI coleta informações sobre o endpoint que você está prestes a criar. Abaixo estão as perguntas e as respostas que você deve fornecer. Lembre-se de pressionar Enter após cada resposta.

Com essas informações, a CLI inicia o processo de geração da URL e, ao terminar, você verá a URL impressa na tela e a CLI indicando que está pronta para receber requisições.

Copie a webhook URL, porque ela será necessária na próxima seção.

Configure o webhook na Stripe

Agora que concluímos a configuração na aplicação de destino, é hora de assinar um webhook na Stripe.

No seu dashboard da Stripe, acesse Developers → Webhooks. Na página "Webhooks", clique no botão + Add endpoint no canto superior direito da tela. Essa ação abrirá um diálogo parecido com o abaixo:

No diálogo, adicione a URL de webhook copiada da CLI no campo Endpoint URL. Em seguida, clique no dropdown Events to send e selecione o evento account.updated, que será disparado sempre que a sua conta Stripe for atualizada. Clique no botão Add endpoint para concluir o processo.

Isso criará a conexão entre a sua conta Stripe e a aplicação rodando na sua máquina local para o evento account.updated. Depois que o webhook for adicionado com sucesso, você verá uma tela como esta:

Teste as requisições de webhook

Com a conexão de webhook configurada, é hora de testá-la. A Stripe oferece uma forma de enviar um webhook de teste que simula o evento assinado. Isso é muito prático para testes e depuração.

Para saber mais sobre testes de webhooks, veja o nosso guia completo de testes de webhooks.

No canto superior direito da tela do webhook mostrada acima, clique no botão Send test webhook. Isso abrirá um diálogo para você selecionar o evento do qual quer enviar o teste. Veja o diálogo abaixo:

Selecione o evento account.updated e clique no botão Send test webhook. Isso disparará uma requisição de webhook para a sua URL, que será recebida no endpoint informado ao criar a URL (ou seja, /stripe-webhooks-endpoint).

Observe a janela do terminal em que você executou o comando hookdeck listen 1337. Você verá a requisição de webhook impressa no terminal, como mostrado abaixo:

O último item da informação impressa é um endereço para você ver detalhes sobre a requisição de webhook recém-recebida. Copie essa URL e abra no navegador; você verá uma tela de detalhes do evento como a abaixo.

Essa tela contém detalhes sobre a requisição de webhook e também o corpo enviado no payload, se houver. Isso permite inspecionar os dados da requisição e escrever código para respondê-los.

Considerações importantes

Webhooks são um mecanismo de comunicação simples e, por isso, é tentador banalizar o processo. No entanto, há pontos muito importantes a considerar ao trabalhar com webhooks, e alguns deles estão explicados abaixo.

Escalabilidade

‍Quanto mais eventos você assina, mais requisições recebe, e alguns eventos são de alta frequência. Não é incomum ver picos repentinos de tráfego ao trabalhar com webhooks. Essa enxurrada de requisições vinda de um evento de alta frequência pode acabar derrubando o seu servidor se o endpoint for sobrecarregado. Uma das formas de resolver isso é o processamento assíncrono com filas de mensagens, ou usar um serviço online como a Hookdeck.

Falha de requisição

‍A maioria das requisições de webhook segue um processo fire-and-forget, em que a requisição é enviada sem que a origem confirme se ela chegou ao destino com sucesso. Assim, se ocorrer um erro no seu endpoint e a requisição não for reenviada, esses dados podem se perder. Isso pode trazer consequências sérias para a integridade do seu sistema. Você quer garantir que requisições com falha sejam reenviadas e que os dados persistam entre as tentativas. Alguns provedores fazem isso automaticamente ao receber um código de erro da aplicação de destino. Quando o provedor não oferece essa funcionalidade, você precisará montá-la.

Segurança

Como já mencionamos, requisições de webhook são requisições HTTP comuns, então vale prestar atenção à autenticação das requisições enviadas ao seu servidor. Alguns provedores, como a Stripe, têm chaves de API e assinaturas de segurança embutidas nos headers para você autenticar as requisições.

Como a Hookdeck ajuda

Configurar o seu primeiro handler de webhook é simples — mantê-lo confiável conforme o tráfego cresce, os provedores mudam e o time adiciona mais integrações é onde o trabalho de verdade começa. O que começa como um único handler de endpoint vira filas, workers de retry, ferramentas de observabilidade, verificação de assinatura e runbooks operacionais (antes mesmo de você entregar a funcionalidade que os webhooks deveriam sustentar).

O Event Gateway da Hookdeck é infraestrutura gerenciada de webhooks que cuida da ingestão, da entrega com backpressure, dos retries, da observabilidade e da verificação de assinatura desde o primeiro dia. Ele fica entre os seus provedores de webhooks e a sua aplicação como uma fila gerenciada — absorvendo picos de tráfego, bufferizando entregas e dando um trace completo de cada evento sem que você precise operar nada disso. Comece com a Hookdeck e pule os meses de encanamento que uma infraestrutura de webhooks em produção normalmente exige.

Conclusão

Webhooks oferecem um sistema de comunicação fluido e em tempo real para aplicações online. As aplicações podem notificar e compartilhar informações umas com as outras sobre eventos que acontecem, formando uma cadeia de fluxos automatizados que gera mais valor para elas e para os seus usuários.

Neste artigo, demonstramos como trabalhar com webhooks usando os webhooks da Stripe como estudo de caso. A maioria dos provedores segue um processo bem parecido, com diferenças apenas no formato da requisição. Assim, você pode transferir o conhecimento adquirido aqui para o trabalho com outros provedores de webhooks. Bons códigos!