O que são webhooks e como eles funcionam?

No mundo online altamente conectado de hoje, nada funciona de forma ideal isoladamente. Realizar uma tarefa (quase) sempre envolve a participação de mais de uma entidade. Aplicações de e-commerce precisam se comunicar com sistemas de pagamento; sistemas de pagamento precisam se comunicar com sistemas bancários; e sistemas bancários precisam se comunicar com contas de clientes — está vendo o padrão?

A interoperabilidade entre sistemas online independentes — a capacidade de se comunicarem entre si e compartilharem dados em tempo real — está no centro do que torna os serviços online valiosos hoje. Neste artigo, vamos olhar para os webhooks, uma das formas mais comuns de facilitar a comunicação entre serviços online. Ao final, você vai entender com clareza o que eles são, como funcionam e quando usá-los.

O que é um webhook?

Um webhook é uma requisição HTTP disparada por um evento em um sistema de origem e enviada para um sistema de destino, muitas vezes com um payload de dados. Webhooks são automáticos; em outras palavras, são enviados automaticamente quando o evento correspondente ocorre no sistema de origem.

Eles dão a um sistema (a origem) uma forma de enviar dados por uma requisição HTTP para outro sistema (o destino) quando um evento acontece, compartilhando informações (o payload da requisição) sobre esse evento.

Para que serve um webhook?

Webhooks são usados para comunicar a um sistema que um evento aconteceu em outro sistema, e normalmente compartilham dados sobre esse evento. Vamos a um exemplo concreto.

Digamos que você assine um serviço de streaming. O serviço quer te enviar um e-mail quando cobrar o seu cartão de crédito.

O serviço de streaming pode se inscrever no serviço bancário (a origem) para que ele envie uma requisição HTTP (webhook) quando um cartão de crédito for cobrado (o gatilho do evento) para o seu serviço de e-mail (o destino). Quando o evento é processado, você é notificado a cada cobrança no seu cartão.

Os webhooks do sistema bancário incluem informações sobre a cobrança (os dados do evento), que o serviço de e-mail usa para montar uma mensagem adequada para você, o cliente.

Eles costumam ser a porta de entrada para desenvolvedores que constroem aplicações orientadas a eventos e arquiteturas orientadas a eventos (EDAs).

Casos de uso comuns de webhooks

Webhooks são usados em quase todas as categorias de serviço online. Estes são alguns dos padrões mais comuns:

Pagamentos e cobrança — processadores de pagamento como Stripe e PayPal enviam webhooks quando cobranças são aprovadas, falham ou são estornadas. Plataformas de assinatura enviam webhooks quando um plano é atualizado, cancelado ou entra em um ciclo de cobrança recorrente com falha. Esses eventos normalmente disparam ações downstream, como liberar acesso, enviar recibos ou atualizar registros de cobrança.

E-commerce e estoque — plataformas como a Shopify enviam webhooks para novos pedidos, mudanças de estoque e atualizações de fulfillment. Esses eventos alimentam sistemas de armazém, transportadoras e ferramentas contábeis que precisam reagir à atividade de pedidos em tempo real.

Ferramentas de desenvolvimento e CI/CD — o GitHub envia webhooks quando código é enviado, pull requests são abertos ou issues são criadas. Pipelines de CI/CD usam esses eventos para disparar builds, rodar testes e fazer deploy automaticamente.

Comunicação e mensageria — serviços como Twilio e SendGrid usam webhooks para notificar a sua aplicação quando mensagens são entregues, abertas ou retornadas. Plataformas de chat como o Slack enviam webhooks para novas mensagens, reações e eventos de canal.

CRM e marketing — plataformas como a HubSpot enviam webhooks quando contatos são criados, negócios mudam de estágio ou formulários são enviados. Esses eventos alimentam fluxos automatizados como roteamento de leads, sequências de nutrição e sincronização de dados entre ferramentas.

Infraestrutura e monitoramento — plataformas de nuvem e ferramentas de monitoramento enviam webhooks para eventos de deploy, alertas, atualizações de incidentes e mudanças de recursos. Esses eventos alimentam sistemas de plantão, dashboards e fluxos automatizados de remediação.

Em todos esses casos, o padrão é o mesmo: um evento acontece em um sistema, e um webhook entrega dados sobre esse evento a outro sistema em tempo real. A diferença está no que acontece depois — e é aí que tratar webhooks de forma confiável se torna importante.

Webhook vs. API

Webhooks e APIs permitem a comunicação entre sistemas, mas funcionam em direções opostas.

Uma API é baseada em requisição. A sua aplicação envia uma requisição HTTP para o endpoint de outro sistema e recebe uma resposta. Você decide quando perguntar, e precisa continuar perguntando se quiser se manter atualizado. Isso costuma ser chamado de polling: o seu sistema verifica se há dados novos em intervalos regulares, tenha algo mudado ou não.

Um webhook é baseado em evento. O outro sistema envia uma requisição HTTP para o seu endpoint assim que algo acontece. Você não pergunta — você é avisado. É por isso que webhooks às vezes são chamados de APIs reversas ou push APIs: o servidor empurra os dados para o cliente, em vez de o cliente puxá-los.

A diferença central está em quem inicia a comunicação:

• API (pull): o seu sistema pergunta "mudou alguma coisa?" de tempos em tempos. É simples de implementar, mas desperdiça recursos quando nada mudou e introduz atraso entre as verificações.
• Webhook (push): o sistema de origem avisa "acabou de mudar algo" no momento em que acontece. É mais eficiente e em tempo real, mas exige que o seu sistema esteja pronto para receber requisições a qualquer momento.

Na prática, a maioria das integrações usa os dois. No nosso exemplo do serviço de streaming, ele usaria a API do serviço bancário para criar uma nova assinatura e receberia um webhook a cada mês, quando a assinatura fosse cobrada. A API cuida das ações que você inicia; o webhook cuida dos eventos aos quais você precisa reagir.

Para uma comparação mais aprofundada, veja o nosso guia sobre quando usar webhooks.

Como os webhooks funcionam

Para um sistema enviar webhooks, ele precisa conseguir fazer requisições HTTP de saída em resposta a um evento interno. Você pode construir o seu sistema para enviar webhooks disparando requisições HTTP para diferentes tipos de evento.

Eles são mais comuns em plataformas SaaS e PaaS como GitHub, Shopify, Stripe e Twilio, porque essas plataformas suportam diferentes tipos de evento com base nas atividades que acontecem nelas.

Para receber requisições de webhook, você precisa se registrar em todos ou em eventos específicos (também chamados de topics) que a plataforma oferece. Esses eventos representam os gatilhos, como charge.created ou user.created, para citar alguns exemplos.

Algumas plataformas exigem que um handshake ou challenge seja concluído antes que o registro seja bem-sucedido. É um processo obrigatório para verificar que a URL é válida e que de fato quer receber requisições do sistema de origem.

Depois de se registrar em um evento, você passa a receber requisições na URL de destino que informou a cada vez que o evento ocorrer.

Consumindo um webhook

Webhooks são requisições HTTP comuns e devem ser tratados como tal. O endpoint HTTP precisa suportar o método HTTP usado pelo provedor e o content type da requisição. Os payloads normalmente usam JSON, form-encoded ou XML, formatos suportados pela maioria dos servidores HTTP.

Eles são enviados com mais frequência pelo método HTTP POST. No entanto, isso depende do provedor. Requisições GET têm o payload anexado à URL como query string. Requisições POST e PUT levam o payload no corpo da requisição e podem conter propriedades como tokens de autenticação.

Há várias coisas a considerar para consumir webhooks com sucesso e evitar problemas de integridade.

Garantias de entrega e idempotência

Webhooks normalmente têm garantia de entrega "at-least-once", o que significa que é possível receber a mesma requisição mais de uma vez. Você deve tornar o seu processamento idempotente.

Timeouts

Requisições de webhook têm um timeout para quanto tempo esperam por uma resposta do seu servidor. Esse timeout normalmente é curto: no máximo 5 segundos e, às vezes, apenas 1 segundo. A boa prática é retornar um status code HTTP 200 para confirmar que você recebeu a requisição.

Controle de throughput

Os webhooks enviados pelos provedores não têm controle de throughput, e é bem provável que em algum momento você receba mais requisições do que consegue processar. Para não perder dados, persista-os imediatamente, geralmente usando uma fila de mensagens, e processe o evento de forma assíncrona.

Processamento assíncrono

Por causa do timeout curto e da falta de controle de throughput, webhooks devem ser processados de forma assíncrona. Processando de forma assíncrona, você garante que o seu sistema responda rapidamente à requisição e adie qualquer processamento demorado para um job em background.

Ordenação

Não há garantia de que os webhooks sejam entregues em ordem, e eles normalmente incluem um timestamp no payload ou nos headers. Esse timestamp pode ser usado para determinar se um evento está fora de ordem ou "obsoleto", evitando que seja processado.

Segurança e verificação de assinatura

Como webhooks são, no fim das contas, requisições HTTP feitas a uma URL "pública", eles são suscetíveis a falsificação por agentes maliciosos. A autenticidade pode ser verificada validando a assinatura da requisição. Normalmente, a assinatura usa algoritmos HMAC com uma chave secreta compartilhada para gerar um hash do corpo da requisição. A assinatura precisa ser calculada e comparada com a assinatura da requisição a cada requisição. Se as assinaturas não baterem, a requisição deve ser rejeitada.

Siga o nosso guia de segurança de webhooks para saber mais sobre como proteger a sua aplicação.

Próximos passos

Agora que você entende os webhooks, talvez esteja se perguntando sobre os desafios práticos de implementá-los em produção. Como você viu, webhooks exigem um tratamento cuidadoso de timeouts, retries, segurança e processamento assíncrono.

Continue aprendendo com os nossos guias

A Hookdeck tem guias completos para você dominar a implementação de webhooks:

• Receba o seu primeiro webhook - comece em minutos.
• Boas práticas para produção - escale com confiabilidade.
• Guia de segurança de webhooks - proteja os seus sistemas.

Veja webhooks em ação com a Hookdeck

Se você está pronto para implementar webhooks, a Hookdeck oferece a infraestrutura para lidar com a complexidade — dos testes até a produção. Experimente gratuitamente e veja como um event gateway simplifica a gestão de webhooks.