A resposta curta
Um webhook é uma requisição HTTP que um sistema envia para outro quando algo acontece. Em vez de a sua aplicação perguntar ao Stripe a cada poucos segundos "alguém já pagou?", o Stripe chama uma URL que você informou no momento em que o pagamento é concluído.
Essa URL é o seu endpoint de webhook. O corpo da requisição descreve o evento, normalmente em JSON, e os cabeçalhos trazem metadados, como uma assinatura que prova quem enviou.
Um exemplo
Assim é um webhook típico, resumido:
POST /webhooks/stripe HTTP/1.1
Host: api.seuapp.com
Content-Type: application/json
Stripe-Signature: t=1793952000,v1=5257a869e7ec…
{"id":"evt_1Q…","type":"invoice.paid","data":{"object":{…}}}O seu endpoint faz três coisas: verifica a assinatura, registra o evento e responde rápido com um 2xx. Qualquer outra resposta (um 5xx, um timeout, uma conexão interrompida) indica ao remetente que a entrega falhou, e a maioria tenta de novo mais tarde.
Para que serve um webhook?
Para saber do que acontece em outros sistemas assim que acontece:
- Pagamentos: Stripe ou PayPal avisam de uma cobrança, um reembolso ou uma assinatura cancelada.
- Código: o GitHub avisa de um push ou de um pull request e dispara o seu CI.
- Lojas: a Shopify avisa de um novo pedido.
- Mensagens: um webhook do Discord ou do Slack publica uma mensagem num canal.
- Automação: n8n ou Zapier iniciam um fluxo quando chega uma requisição.
Webhook vs. API
Com uma API, você pergunta quando quiser: "me dê a fatura 42". Com um webhook, o outro sistema avisa quando algo acontece: "a fatura 42 acabou de ser paga". Em resumo: com uma API, você chama; com um webhook, chamam você.
| API | Webhook | |
|---|---|---|
| Quem inicia a requisição | Você | O provedor |
| Quando | Quando você decide | Quando ocorre um evento |
| Se nada acontece | Você continua gastando requisições | Nada é enviado |
| Quem hospeda o endpoint | O provedor | Você |
Integrações robustas usam os dois: o webhook avisa que algo mudou e a API devolve o estado atual. Mais detalhes (em inglês) em webhook vs. API.
O que pode dar errado
Webhooks são fáceis de começar e fáceis de errar:
- O seu endpoint está fora do ar durante um deploy e o provedor desiste depois das suas tentativas.
- Alguém forja uma requisição para a sua URL pública porque a assinatura não é verificada. Veja assinaturas HMAC (em inglês).
- O mesmo evento chega duas vezes e a sua aplicação cobra, envia ou entrega duas vezes. Veja retentativas e idempotência (em inglês).
- Ninguém sabe o que aconteceu, porque nem a requisição nem a resposta foram registradas.
Onde o HookStead entra
O HookStead dá a cada provedor uma URL estável, verifica a assinatura na chegada, armazena cada evento antes de responder e o encaminha para a sua aplicação com retentativas, a sua própria assinatura e um registro completo de cada tentativa. Quando algo quebra, você vê, corrige o endpoint e reenvia. O plano gratuito inclui 10.000 eventos por mês; veja a documentação (em inglês).
Perguntas frequentes
- O que é webhook em palavras simples?
- É um aviso automático: quando algo acontece num sistema (um pagamento, um pedido, um push), esse sistema envia uma requisição HTTP para uma URL sua com os dados do evento.
- Qual a diferença entre webhook e API?
- Com uma API, você pede os dados quando quiser. Com um webhook, o outro sistema envia os dados para você quando ocorre um evento.
- O que é uma URL de webhook?
- É o endereço para onde o remetente envia os webhooks. Ela deve ser pública, usar HTTPS e responder rápido com um código 2xx.