O que é um webhook? Como os apps se avisam

Um webhook é uma mensagem automática que um serviço envia ao seu app no exato momento em que algo acontece. Quando o pagamento de um cliente é aprovado, o Stripe envia um webhook para um endereço do seu app dizendo "pagamento aprovado, aqui estão os detalhes", e seu app reage — marca o pedido como pago, envia o recibo, libera a conta. Resumindo: uma API é o seu app fazendo uma pergunta a outro serviço; um webhook é o outro serviço chamando o seu app para contar algo.

Por que isso importa quando você cria com IA

Assim que seu app recebe pagamentos, recebe envios de formulários de outra ferramenta ou se conecta a serviços como GitHub, Shopify ou uma agenda, você vai encontrar webhooks. Geralmente são a forma correta de saber que algo aconteceu — mas também é onde apps criados com IA costumam errar de forma sutil:

• O endpoint aceita qualquer requisição, então qualquer pessoa pode simular um evento de "pagamento aprovado".
• O app libera o acesso na página de retorno do checkout, em vez de fazê-lo no webhook; assim, quem fecha a aba cedo nunca recebe o que pagou, e quem descobre a URL de sucesso recebe de graça.
• O mesmo evento chega duas vezes e o cliente recebe dois pedidos ou dois e-mails.

Entender como os webhooks funcionam permite pedir as proteções desde o início.

Uma analogia do dia a dia: o SMS de entrega

Você pode descobrir se sua encomenda chegou de duas formas. Pode ir até a porta a cada dez minutos para conferir (isso é polling — seu app chamando repetidamente uma API para perguntar "há algo novo?"). Ou o entregador pode mandar um SMS quando entregar (isso é um webhook).

O SMS é claramente melhor — desde que você possa confiar nele. Se qualquer pessoa pudesse enviar a mensagem "encomenda entregue", você gostaria de ter como saber que ela realmente veio do entregador. E se o seu celular estivesse desligado quando o SMS chegou, você gostaria que o entregador tentasse de novo depois. Essas duas preocupações — verificação e novas tentativas — são a maior parte do que torna os webhooks complicados.

Como um webhook funciona, passo a passo

1. Você cria um endpoint no backend do seu app: uma URL como https://seuapp.com/webhooks/stripe que aceita requisições POST.
2. Você registra essa URL no provedor e escolhe quais eventos quer receber (por exemplo, "checkout concluído" e "assinatura cancelada").
3. O provedor entrega um segredo de assinatura. Você o guarda como segredo no seu servidor — veja variáveis de ambiente e segredos.
4. Um evento acontece. O provedor envia uma requisição HTTP para a sua URL com um corpo JSON descrevendo o evento, além de um cabeçalho de assinatura.
5. Seu app verifica a assinatura, registra o ID do evento, responde rapidamente com um código de sucesso (200) e só então faz o trabalho.
6. Se seu app não responder com sucesso, muitos provedores tentam de novo mais tarde.

Assinaturas

Uma assinatura prova que a requisição veio do provedor e não foi alterada. O Stripe, por exemplo, calcula um HMAC (uma espécie de impressão digital com chave) com SHA-256 sobre o corpo da requisição e um carimbo de data/hora, usando o segredo de assinatura, e envia o resultado em um cabeçalho Stripe-Signature. Seu app faz o mesmo cálculo com a sua cópia do segredo; se os resultados baterem, a requisição é autêntica. Como o carimbo de tempo também é assinado, você pode rejeitar requisições antigas que alguém tenha gravado e reenviado depois — as bibliotecas do Stripe usam, por padrão, uma tolerância de cinco minutos, segundo a documentação do provedor em setembro de 2026.

Um detalhe prático: a assinatura é calculada sobre o corpo bruto da requisição. Se seu framework interpretar e reformatar o JSON antes da verificação, a checagem falha. Esse é um erro muito comum.

Novas tentativas, duplicatas e ordem

Os provedores são diferentes, então confira a documentação de cada um. Em setembro de 2026:

A documentação do Stripe também diz que os eventos não são garantidos na ordem em que aconteceram, e que o mesmo evento pode, ocasionalmente, chegar mais de uma vez; por isso recomenda registrar os IDs dos eventos.

A lição geral vale para qualquer provedor: os eventos podem chegar atrasados, mais de uma vez e fora de ordem. Seu manipulador deve ser idempotente — processar o mesmo evento duas vezes tem o mesmo efeito de processá-lo uma vez.

Um exemplo prático: liberando um curso pago

Você vende um curso online. Um aluno clica em Comprar, paga na página de checkout hospedada pelo Stripe e volta para o seu site.

O jeito frágil: a página de "obrigado" libera o curso. Se o aluno fechar o navegador durante o redirecionamento, ele pagou mas não tem acesso. Se alguém adivinhar a URL de agradecimento, ganha acesso sem pagar.

O jeito com webhook:

1. Quando o Stripe confirma o pagamento, envia um evento checkout.session.completed para /webhooks/stripe.
2. Seu backend verifica a assinatura com o segredo de assinatura. Se falhar, responde 400 e não faz mais nada.
3. Ele verifica se aquele ID de evento já foi processado. Se sim, responde 200 e para.
4. Ele registra o ID do evento, responde 200 e então libera o acesso do aluno e envia um e-mail de boas-vindas.
5. A página de agradecimento apenas diz "Pagamento recebido — seu curso aparecerá em instantes" e consulta o status de acesso do aluno.

Depois, se uma assinatura for cancelada ou um cartão falhar, outros eventos de webhook dizem ao seu app para remover ou pausar o acesso. É assim que produtos por assinatura permanecem sincronizados com a cobrança — veja o que é SaaS e como adicionar pagamentos ao seu app.

Termos principais

• Endpoint: a URL do seu app que recebe os webhooks.
• Evento / payload: o que aconteceu, e os dados que descrevem o fato (geralmente em JSON).
• Segredo de assinatura: o segredo compartilhado usado para verificar as assinaturas.
• Idempotente: seguro para executar mais de uma vez com o mesmo resultado.
• Polling: perguntar repetidamente a uma API por mudanças, em vez de esperar um webhook.
• Túnel: uma ferramenta que dá a um notebook uma URL pública temporária para que os webhooks cheguem a ele durante o desenvolvimento.

Erros comuns e ideias erradas

• Não verificar assinaturas. A URL do endpoint não é segredo. A verificação é o que torna a requisição confiável.
• Fazer trabalho lento antes de responder. Enviar e-mails ou gerar PDFs antes de responder pode causar timeouts, que disparam novas tentativas, que geram duplicatas.
• Presumir entrega única e em ordem. Registre os IDs dos eventos e não dependa da ordem de chegada.
• Usar uma URL de prévia. Webhooks precisam de um endereço público e estável. Prévias privadas e localhost não são acessíveis pela internet; use sua URL publicada (ou um túnel durante os testes).
• Misturar segredos de teste e de produção. Os provedores costumam emitir segredos de assinatura diferentes para os modos teste e live. Guarde os dois e use o correto.
• Confiar cegamente no payload para decisões importantes. Para ações de alto risco, é razoável buscar o estado mais recente na API do provedor depois de receber o evento.

O que pedir ao seu criador de apps com IA

Adicione um endpoint POST /webhooks/stripe no servidor. Verifique a assinatura do Stripe usando o corpo bruto da requisição e o segredo STRIPE_WEBHOOK_SECRET. Rejeite assinaturas inválidas com 400. Guarde o ID de cada evento e ignore eventos já processados. Responda 200 rapidamente e depois trate checkout.session.completed marcando o pedido como pago e enviando o recibo. Registre o tipo do evento. Não libere acesso a partir da página de sucesso do checkout.

Em seguida, teste: envie um evento de teste pelo painel do provedor, envie o mesmo evento novamente e envie uma requisição com assinatura errada. Apenas a primeira deve alterar algo.

Webhooks no Mythex

O Mythex não executa um serviço de webhooks separado; você pede ao agente para adicionar um endpoint de webhook no próprio backend do seu app, e aponta o provedor para a sua URL publicada, já que webhooks precisam de um endereço público. O segredo de assinatura vai para os segredos do projeto, e se você alterá-lo em um app no ar, publique de novo. A receita de documentação sobre como tratar webhooks tem um prompt inicial, e os templates de loja são um bom ponto de partida para apps que recebem pagamentos.

Perguntas