Programação · conceitos · web

O que é um webhook?

Configuras um pagamento, e a tua aplicação reage no instante em que o dinheiro é cobrado. Envias um commit, e uma build arranca sozinha. Por detrás dessa imediatez está quase sempre um webhook. Este guia explica, de forma simples, o que é um webhook, em que difere de uma chamada de API clássica, como recebê-lo em segurança e onde já dependes dele.

A definição curta

Um webhook é um pedido HTTP automático que um serviço envia para um URL que tu controlas quando ocorre um evento. Em vez de pedires notícias a um serviço, é ele que avisa a ti assim que as há.

Daí a alcunha de «API invertida». Com uma API clássica, és o cliente: fazes o pedido, o servidor responde. Com um webhook os papéis invertem-se — o fornecedor torna-se o cliente e o teu endpoint é o servidor que ele chama.

Webhook vs polling de uma API

Antes dos webhooks, a forma habitual de manter-se atualizado era o polling: chamar uma API num temporizador («há novidades?») uma e outra vez. É simples mas desperdiçador — a maioria das chamadas não devolve nada, e há sempre um desfasamento entre o evento e a verificação seguinte.

• Polling — pedes em ciclo. Muitos pedidos inúteis, reação atrasada, simples de construir.
• Webhook — o serviço avisa-te uma vez, imediatamente. Eficiente e quase em tempo real, mas tens de manter um endpoint para o receber.

Como funciona, passo a passo

1. Registas um URL (o teu endpoint) junto do fornecedor e escolhes os eventos que te interessam.
2. Quando um tal evento ocorre, o fornecedor envia um POST HTTP para o teu URL com um corpo (muitas vezes JSON) que o descreve.
3. O teu servidor lê o conteúdo, devolve depressa um estado 2xx para o acusar, e faz o verdadeiro trabalho a seguir.
4. Se o teu endpoint estiver offline ou devolver um erro, a maioria dos fornecedores repete com backoff — daí os possíveis duplicados.

Uma entrega assemelha-se a qualquer pedido HTTP:

POST /webhooks/payments  HTTP/1.1
Host: atuaapp.com
X-Signature: t=1718600000,v1=9f86d08...

{ "event": "payment.succeeded", "id": "pay_42", "amount": 1999 }

Exemplos que já conheces

• Pagamentos — o Stripe e o PayPal enviam um webhook quando um pagamento é bem-sucedido, falha ou é reembolsado, para que a tua app atualize a encomenda sem polling.
• Alojamento de código — o GitHub e o GitLab disparam um webhook em push, pull request ou issue: é assim que builds de CI e bots são lançados.
• Mensagens — o Slack, o Discord e as plataformas de chat usam webhooks de entrada para publicar mensagens e notificar a tua app.

Recebê-lo em segurança

Um recetor robusto faz quatro coisas:

• Servir em HTTPS e aceitar os POST; responder depressa com um 2xx, depois processar de forma assíncrona.
• Verificar a assinatura — os fornecedores assinam o corpo (um HMAC com um segredo partilhado). Rejeitar o que falha.
• Ser idempotente — o mesmo evento pode chegar várias vezes; usa o id do evento para que a reentrega seja sem efeito.
• Devolver os erros honestamente — se não conseguires processar, devolve um não-2xx para que o fornecedor repita em vez de desistir.

Os webhooks precisam de um endpoint sempre online com um URL HTTPS público — é por isso que um pequeno servidor ou uma instância cloud é a casa habitual de um recetor de webhooks, e não uma máquina que adormece.

Perguntas frequentes

O que é um webhook, em termos simples?

Um webhook é uma mensagem automática que um serviço envia para um URL que tu controlas no instante em que algo acontece — por exemplo «um pagamento foi bem-sucedido» ou «um commit foi enviado». Em vez de perguntares sem parar ao serviço «há novidades?» (o polling da sua API), o serviço chama-te com um pedido HTTP POST assim que o evento ocorre. Fala-se muitas vezes de «API invertida»: com uma API clássica és tu a fazer o pedido; com um webhook é o serviço a fazê-lo a ti.

Qual é a diferença entre um webhook e uma API?

Estão ligados mas vão em sentido inverso. Com uma API (REST) clássica, envias um pedido ao fornecedor quando queres dados, e ele responde. Com um webhook, o fornecedor envia um pedido ao teu servidor quando ocorre um evento: os dados são-te empurrados quase em tempo real sem pedires nada. Um webhook passa pela mesma mecânica HTTP de uma API — é o fornecedor que faz o papel de cliente e o teu endpoint o de servidor.

Porquê um webhook em vez de polling?

O polling consiste em chamar uma API em intervalos regulares para verificar mudanças, o que desperdiça pedidos e acrescenta um atraso entre o evento e a tua reação. Os webhooks empurram-te o evento no instante em que chega: mais eficientes e muito mais próximos do tempo real. Em contrapartida, tens de manter um endpoint sempre online e gerir as repetições e as entregas em duplicado.

Como receber um webhook em segurança?

Expõe um endpoint HTTPS que aceite POST, devolve depressa um estado 2xx para acusar a receção, depois processa o trabalho de forma assíncrona. Verifica a assinatura que o fornecedor envia (um HMAC do corpo com um segredo partilhado) para confirmar a autenticidade, e torna o processamento idempotente, pois um mesmo evento pode ser entregue várias vezes. Rejeita tudo o que não passe a verificação da assinatura.

Em resumo

Um webhook é a forma da web de dizer «não nos chames, nós chamamos-te»: um pedido HTTP automático que um serviço envia para o teu endpoint assim que ocorre um evento. É mais eficiente e muito mais em tempo real do que o polling de uma API — ao preço de um endpoint fiável, que verifica as assinaturas, para o receber. Uma vez identificados, vais ver os webhooks por detrás de quase todos os «atualizou-se sozinho» do software moderno.