Em Que Consiste Essa Técnica

O que são Webhooks e por que a maioria das pessoas implementa errado na primeira vez

A técnica de webhooks nada mais é do que um mecanismo de notificação push via HTTP onde um serviço A chama uma URL que você especificou quando um evento ocorre. O oposto disso seria o polling, onde você fica perguntando a cada X segundos se algo mudou. Parece simples, mas a execução real é onde o problema mora. Eu já vi gente configurar webhooks pra receber atualizações de pagamento de um gateway e perder cobranças porque o endpoint deles tava fora do ar por 47 minutos e o provedor desistiu de retry depois de 3 tentativas. O que as documentações não te contam é que quase nenhum provedor garante entrega exatamente uma vez. Isso se chama "at-least-once delivery" e você precisa projetar pra isso desde o início.

em que consiste essa técnica na prática

Vamos ao passo a passo real, não o que tá no blog de marketing da Stripe ou do GitHub. Primeiro, você cria um endpoint HTTP público. Pode ser qualquer coisa: uma rota num Express, um function serverless, até um script PHP num servidor antigo. O importante é que esse endpoint aceite requisições POST com payload JSON. Mas aqui vem a parte que todo mundo erra: você precisa validar o payload antes de fazer qualquer coisa com ele. Não confie no que chega. Webhooks podem ser disparados por qualquer pessoa que descubra a URL do seu endpoint, mesmo sem o segredo correto.

Para validar, a maioria dos provedores usa uma assinatura criptográfica. Eles enviam um header como X-Shopify-Hmac-SHA256 ou X-Hub-Signature-256 que é um hash HMAC do corpo da requisição usando uma chave secreta. No Node.js, por exemplo, o código de validação é algo como: crypto.createHmac('sha256', segredo).update(body).digest('hex') === signature

Se o hash não bater, descarta a requisição. Sem negociação. Já tive um endpoint recebendo requisições de testing de bots que gastavam meu quota diário porque eu só confiava no método POST e não validava o HMAC. Depois de validar, sua resposta deve ser rápida. O padrão é responder com status 200 em menos de 5 segundos. Se você precisa processar algo que leva mais tempo, faça isso de forma assíncrona: aceite o webhook, responda 200, e processe o evento numa fila. Use uma fila como o RabbitMQ, SQS, ou até uma tabela no banco com status "pending" se o volume for baixo. Eu trabalhava num sistema que processava webhooks de logística direto na threads síncrona e o timeout do provedor cortava 30% das requisições porque o cálculo de rotas levava 12 segundos. Depois que migrei pra fila com retry exponencial, a taxa de sucesso subiu pra 99,7%.

os problemas que ninguém conta

O maior pesadelo com webhooks é a duplicação. Um mesmo evento pode chegar duas, três, cinco vezes. Eu passei dois dias caçando um bug num sistema de estoque onde o webhook de "produto atualizado" chegava duplicado e o sistema reduzia o estoque duas vezes, gerando quantidade negativa. A solução foi implementar deduplicação usando o ID do evento que o provedor inclui no payload. Cada webhook vem com um campo id ou event_id único. Você armazena esses IDs num set ou tabela com TTL e ignora os que já foram processados. Outro problema comum é a URL expirar. Se você tá desenvolvendo localmente, o webhook não vai entregar porque sua máquina não é acessível publicamente. Ferramentas como ngrok resolvem isso, mas elas criam uma URL temporária que muda toda vez que o túnel reinicia. Num projeto real, configurei um túnel ngrok no docker-compose e esqueci que o token era efêmero. Quando o container reiniciou, todos os webhooks passaram a retornar 404 e eu demorei três horas pra perceber porque o log do provedor mostrava "delivery attempted" mas o meu log local não tinha nada.

Também tem o problema de ordem. Eventos relacionados podem chegar fora de ordem. Se você tem um webhook de "criar pedido" e outro de "atualizar endereço", é possível que a atualização chegue antes da criação e seu sistema tente atualizar um registro que ainda não existe. A solução mais pragmática é implementar retry com delay crescente e, em casos críticos, colocar um state machine que lide com eventos fora de ordem verificando o estado atual antes de aplicar a mudança.

quando não usar webhooks

Nem sempre webhooks são a resposta certa. Se você precisa de dados em tempo real absolutamente garantidos e o provedor não oferece webhook, fique com polling. É mais barato sofrer com requisições desnecessárias do que lidar com a complexidade de gerenciar entrega falhada, validação criptográfica e deduplicação. Um polling simples com intervalos de 30 segundos e cache local resolve 90% dos casos onde webhooks parecem a solução óbvia mas na verdade são overengineering. Também evite webhooks se o volume de eventos for baixo e previsível. Receber 2 webhooks por dia de um serviço de newsletter é mais trabalho do que vale a pena. Um cron job que roda a cada hora e busca atualizações via API é mais simples de debugar e não exige endpoint público, validação HMAC, ou fila de processamento.

A regra prática que eu uso: se o evento acontece mais de 10 vezes por minuto e a latência de entrega importa, webhook. Senão, polling ou API de consulta direta. Simple.