Por que implementar processamento assíncrono de webhooks

Como desenvolvedor, garantir que o seu back-end funcione bem é essencial para entregar serviços confiáveis. Se você não recebe e processa os seus webhooks corretamente, corre o risco de ter desempenho ruim e quedas de servidor, o que pode afetar negativamente o seu produto, os seus usuários e o seu time.

Neste guia de referência independente de linguagem, você vai aprender a levar os seus webhooks para o próximo nível implementando processamento assíncrono, um dos conceitos mais importantes na construção de webhooks confiáveis. No caminho, vamos cobrir o básico de ingestão, enfileiramento, processamento, retries e alertas.

Depois de ler este guia, você vai ter um entendimento sólido do que é necessário para construir uma infraestrutura de webhooks robusta e bem projetada.

Infraestrutura de webhooks gerenciada para você.

O Hookdeck cuida do enfileiramento, da entrega e da observabilidade — para você focar em construir o seu produto.

Começar agora Saiba mais

A abordagem mínima para webhooks

Webhooks são considerados assíncronos por natureza. Isso porque nenhuma resposta específica é esperada do seu servidor além de uma confirmação de recebimento.

Desenvolvedores que estão começando com webhooks muitas vezes montam os handlers de um jeito bem simples:

Receber a requisição.
Executar algum método.
Retornar assim que o método terminar.

Embora isso possa parecer uma abordagem sólida para lidar com webhooks, ela tem várias fraquezas.

Fraqueza	Motivo
Você não controla a taxa em que recebe webhooks.	A plataforma que envia webhooks para o seu servidor pode entregar uma rajada de requisições de uma vez. Isso pode acontecer por ações em massa do seu lado (como subir uma nova lista de e-mails em um serviço de e-mail) ou porque a plataforma acumulou um backlog de webhooks para enviar depois de uma indisponibilidade. Seja qual for a causa, dá para ver como um grande volume de requisições em pouco tempo pode sobrecarregar um sistema construído com a abordagem mínima.
Ela não considera erros.	O seu método de tratamento de webhooks pode encontrar um erro porque está ficando sem recursos, porque depende de um terceiro que está retornando erro ou simplesmente porque foi um deploy ruim.
Ela não considera indisponibilidades.	Quedas acontecem, e a sua infraestrutura de webhooks precisa estar preparada para elas. Você não pode presumir que o seu endpoint HTTP vai estar escutando quando o webhook chegar. Em caso de queda, você ainda precisa entregar resultados consistentes.
Ela não considera janelas de timeout.	Muitas plataformas oferecem janelas de timeout curtas na requisição. Se o seu servidor não consegue fazer o trabalho dentro dessa janela, a conexão é encerrada. Na abordagem simplista descrita acima, o método executado ao receber o webhook de entrada precisa terminar antes de a janela fechar, ou a plataforma solicitante pode reportar uma falha – mesmo que o método tenha sucesso depois

Você decidiu que a abordagem mínima não é para você. Bom instinto. Então, como projetar a sua infraestrutura de webhooks? É aqui que entra o processamento assíncrono de webhooks.

O que é processamento assíncrono de webhooks?

Na maior parte do tempo, webhooks são fáceis de tratar. Mas, se o seu servidor recebe requisições demais de uma vez, ele pode ficar sobrecarregado. Some a esse volume crescente todos os outros trabalhos não relacionados que o seu servidor executa, e você pode ter uma indisponibilidade nas mãos.

Um sistema de webhooks bem projetado lida com esses picos de volume de forma eficiente e processa todas as requisições de entrada, independentemente do volume. Para isso, o seu servidor deve fazer o mínimo de trabalho possível ao receber um webhook. Chamamos isso de processamento assíncrono.

Um servidor que segue os princípios do processamento assíncrono primeiro retorna uma resposta HTTP 200 e depois enfileira o evento para ser processado de forma assíncrona pelo seu sistema.

Usar processamento assíncrono tem várias vantagens:

Limita a quantidade de recursos necessários para processar uma requisição.
Dá mais capacidade para lidar com múltiplas requisições concorrentes.
Dá liberdade para aplicar regras e lógicas intensivas em processamento sobre os webhooks de entrada, sem afetar a confiabilidade da sua infraestrutura.

Como implementar processamento assíncrono

Uma infraestrutura de webhooks com processamento assíncrono precisa implementar com sucesso três passos-chave: ingestão, enfileiramento e processamento.

Ingestão

O nosso único objetivo aqui é expor um endpoint HTTP POST simples. Esse endpoint precisa:

Receber webhooks
Armazenar os headers e o corpo da requisição em uma fila
Retornar um código de status HTTP 200

O endpoint deve ser construído para usar o mínimo de recursos possível, o que garante que ele continue escalável.

Serviços serverless como AWS Lambda, Google Cloud Functions e Google Cloud Run se encaixam muito bem na ingestão, já que escalam com facilidade conforme o volume de requisições concorrentes.

Enfileiramento

Depois de receber a requisição com sucesso, precisamos guardá-la para processar mais tarde. A melhor solução aqui é implementar uma fila de mensagens.

Independentemente de como você projeta a sua fila, garanta que ela não vai desmoronar sob carga. A maioria das filas é limitada pelo número de conexões concorrentes ou pelo throughput em GB/s – você quer ter certeza de que o seu sistema de filas consegue acompanhar qualquer pico inesperado de volume. Algumas filas, como AWS SQS e PubSub, são praticamente ilimitadas, o que as torna ótimas candidatas para esse caso de uso.

Uma boa estratégia para economizar custos é armazenar os headers e os corpos dos webhooks em um arquivo no AWS S3 ou no GCP Cloud Storage e enfileirar uma referência ao arquivo em vez do conteúdo em si.

Dependendo da natureza do seu caso de uso, você pode precisar de múltiplas filas para diferentes tópicos ou tipos de webhook. Alguns tipos de requisição são naturalmente mais importantes que outros. Ao introduzir múltiplas filas, você pode atribuir prioridades diferentes a cada uma.

Processamento

Assim que os seus webhooks estiverem em uma fila, você pode processá-los com segurança. Só garanta que isso aconteça em um ritmo razoável para a sua infraestrutura e o seu caso de uso. Filas diferentes adotam abordagens diferentes de processamento – mas, em geral, você vai querer um conjunto de serviços worker, cada um puxando da fila no próprio ritmo.

Como lidar com retries

Um sistema de filas para webhooks é uma ótima forma de receber e processar requisições. Mas até os melhores sistemas de fila podem perder requisições diante de sobrecarga do servidor ou de outros problemas de rede. Quando isso acontece, o seu sistema não completa a transação ou a notificação de evento subjacente, o que pode levar a uma experiência ruim para o usuário. Para lidar com esses casos, precisamos implementar um recurso de retry que dispare em dois cenários: falha de ingestão e falha de processamento.

Retry em falha de ingestão

Se você falha ao receber uma requisição de webhook, vai depender da política de retry do seu provedor. A maioria das plataformas tem alguma forma de estratégia de retry. Se a plataforma não oferece retries, ou se você não consegue receber todas as novas tentativas, vai precisar reconciliar os seus dados consultando a API do provedor. Como isso nem sempre é possível, a confiabilidade do seu serviço de ingestão é crítica.

Retry em falha de processamento

É praticamente garantido que, em algum momento, você vai encontrar erros ao processar a sua fila. Felizmente, dá para aproveitar a própria fila para fazer retries, confirmando (ou não confirmando) as mensagens de forma adequada.

Não esqueça de incluir também uma política de dead letter para separar as mensagens que falham no processamento várias vezes seguidas. Se você não fizer isso, pode acabar entupindo a fila com eventos impossíveis de processar.

Como lidar com alertas

Você precisa saber quando as coisas não estão indo como planejado no seu ambiente de produção. Quando o assunto é processamento adiado de webhooks, há dois pontos em que os alertas se tornam críticos.

Na ingestão

Se o seu serviço de ingestão responde com erro, isso significa que você está ativamente perdendo webhooks. Você vai querer monitorar as respostas HTTP do seu endpoint e configurar um alerta caso o status não seja 2xx. Alguns provedores de API também oferecem alguma forma de alerta se o seu endpoint não retorna uma resposta bem-sucedida.

No envio para uma dead letter queue

Se você falha ao processar uma mensagem várias vezes seguidas, vai querer inspecioná-la para determinar a causa raiz da falha. Você vai querer monitorar a profundidade da sua dead letter queue para ser alertado quando novas mensagens aparecerem.

Como o Hookdeck ajuda

Migrar de processamento síncrono para assíncrono de webhooks significa introduzir uma fila, processos worker, lógica de retry, tratamento de dead letter e as ferramentas operacionais para rodar tudo isso — um investimento considerável antes mesmo de você processar o primeiro evento. Construir isso do zero significa implementar backoff exponencial, rastreamento de falhas, tratamento de dead letter e ferramentas de replay manual, e manter tudo isso ao lado do código do seu produto de verdade.

O Event Gateway do Hookdeck é infraestrutura gerenciada para receber e entregar webhooks de forma confiável. Ele funciona como uma fila gerenciada entre os seus provedores de webhook e a sua aplicação, absorvendo picos de tráfego e amortecendo as entregas em um ritmo que os seus servidores conseguem suportar, agrupa falhas relacionadas em Issues para você ver as causas raiz e fazer retry em massa dos eventos afetados com um clique, e oferece deduplicação nativa para que eventos reenviados nunca produzam efeitos colaterais duplicados. Cada entrega é rastreada ponta a ponta, com payload, headers e dados de resposta completos. Comece a usar o Hookdeck e adicione confiabilidade de nível de produção ao seu pipeline de webhooks sem escrever o código de fila por conta própria.

Conclusão

Você percebeu que a abordagem mínima para webhooks tem fraquezas e que construir uma infraestrutura de webhooks ajuda a se proteger delas. Cobrimos como construir a sua infraestrutura com ingestão, enfileiramento, processamento, retries e alertas.

Se você procura uma plataforma robusta para lidar com toda essa complexidade por você, o Hookdeck te dá cobertura. Você configura e monitora os seus webhooks com facilidade, sem se preocupar com ingestão, enfileiramento ou processos de troubleshooting no seu fluxo de trabalho.

A solução da Hookdeck Produtores de webhooks