HookSteadBETA

O que é webhook? Explicação simples com exemplos

O que é um webhook, como funciona, qual a diferença para uma API e o que é preciso para recebê-los com segurança e sem perder eventos.

5 min de leitura · Atualizado · English · Español

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ê.

APIWebhook
Quem inicia a requisiçãoVocêO provedor
QuandoQuando você decideQuando ocorre um evento
Se nada aconteceVocê continua gastando requisiçõesNada é enviado
Quem hospeda o endpointO provedorVocê

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.