Webhook: O que é, como funciona e diferenças para API

Webhook é um mecanismo que permite que um sistema informe automaticamente outro sistema sobre a ocorrência de um evento. Em vez de realizar consultas constantes ao servidor, o aplicativo recebe os dados exatamente no momento em que eles aparecem, como após um pagamento bem-sucedido, um novo pedido ou uma alteração no status de entrega.

Os webhooks são extremamente úteis na integração de múltiplos serviços. Eles reduzem o número de solicitações desnecessárias e permitem uma reação mais rápida a mudanças. Embora estejam relacionados ao API tradicional, os webhooks funcionam de maneira diferente.

O que é webhook e para que serve

Webhook em termos simples

A diferença entre API e webhook pode ser comparada ao modo como recebemos notificações:

• Com uma API, o aplicativo faz solicitações ao servidor perguntando: "Há novos dados?". Se não houver novidades, ele repete a consulta mais tarde.
• Com o webhook, o aplicativo informa previamente um endereço especial ao serviço, e esse serviço envia notificações para lá sempre que um evento relevante ocorrer.

Por exemplo, uma loja online não precisa checar a todo momento se um pagamento foi efetuado. O serviço de pagamentos pode enviar um webhook assim que o pagamento for confirmado.

Por isso, webhooks são conhecidos como mecanismos de notificação entre sistemas: um sistema apenas aguarda a mensagem do evento necessário, sem consultas constantes.

Quais problemas os webhooks resolvem

Webhooks são usados quando é necessário reagir rapidamente a mudanças em outro serviço. Exemplos comuns incluem:

• sistema de pagamentos informa a loja sobre um pagamento realizado;
• CRM recebe informações sobre um novo lead do site;
• serviço de entregas envia o novo status de um pedido;
• plataforma de Git dispara uma build após upload de código;
• mensageiro envia uma nova mensagem ao bot;
• serviço em nuvem avisa sobre a conclusão do processamento de um arquivo.

A característica principal desses cenários é que a ação é desencadeada por um evento. O sistema não verifica o estado periodicamente - ele recebe o sinal apenas quando algo realmente acontece.

Esse princípio não se limita a integrações simples, mas também é utilizado em sistemas de software robustos. Para saber mais, veja o artigo Por que a arquitetura event-driven torna sistemas mais rápidos e ágeis.

Dessa forma, o webhook é especialmente conveniente para automação. Após receber um evento, o programa pode atualizar o status de um pedido, notificar o usuário, registrar informações em banco de dados ou iniciar outro processo automaticamente.

Como funciona o webhook

Evento, URL e requisição HTTP

Para que um webhook funcione, o sistema receptor cria um URL especial - chamado de endpoint. É para esse endereço que outro serviço enviará notificações sobre eventos.

O fluxo é simples:

1. evento ocorre;
2. serviço gera os dados;
3. envia uma requisição HTTP;
4. sistema receptor processa a informação.

Por exemplo, após um usuário pagar por um pedido, o serviço de pagamentos registra a transação e envia uma requisição HTTP para o webhook da loja online. Ao receber essa notificação, a loja muda o status do pedido para "Pago" e pode acionar outros processos automaticamente.

O método HTTP mais utilizado é o POST, pois é necessário transmitir dados sobre o evento. No entanto, o formato pode variar conforme o serviço.

O que contém uma requisição de webhook

Uma requisição de webhook normalmente inclui:

• O URL do endpoint (endereço do receptor);
• Headers HTTP com possíveis dados de autenticação;
• O corpo da requisição, geralmente em JSON, com informações sobre o evento.

Por exemplo, uma notificação de pagamento pode conter:

{
  "event": "payment.success",
  "order_id": "A1024",
  "status": "paid"
}

O aplicativo lê o campo event para identificar o tipo de evento e aciona a lógica apropriada. Após o processamento, o servidor retorna um código HTTP - um código 200 indica sucesso. Se houver erro ou ausência de resposta, o serviço tentará reenviar a notificação.

Exemplo prático de uso do webhook

Imagine uma loja virtual integrada a um serviço de pagamentos externo. O cliente finaliza o pedido e realiza o pagamento. Assim que o serviço de pagamentos obtém a confirmação do banco, ele envia um webhook para a loja:

• payment.success → webhook da loja → mudança no status do pedido

O servidor da loja processa a notificação e atualiza automaticamente o status para "Pago". Isso pode acionar envio de recibos, notificação ao estoque e início do preparo do produto.

Esse modelo é ideal para processos em que o evento pode ocorrer segundos, minutos ou até horas depois da solicitação inicial, eliminando a necessidade de verificações constantes.

Webhook e API: qual a diferença?

API funciona sob demanda, webhook por evento

A principal diferença entre webhook e API está em quem inicia a troca de dados:

• Com API, o aplicativo faz a solicitação quando quer. Exemplo: buscar lista de pedidos, obter perfil do usuário ou checar status de pagamento.
• Com webhook, o receptor informa previamente seu URL e o serviço envia a notificação assim que o evento acontece.

Esses modelos são conhecidos como pull (API) e push (webhook). A API é utilizada para buscar dados sob demanda, enquanto o webhook envia os dados automaticamente.

Webhook vs REST API

Pelo API, a loja pode consultar informações sobre um pagamento. Pelo webhook, o serviço de pagamentos avisa automaticamente sobre a conclusão do pagamento.

Portanto, não faz sentido tratar webhook e API como tecnologias completamente opostas: na prática, elas se complementam.

Webhook não substitui API

Na maioria dos casos, webhooks e APIs funcionam juntos:

• API é usada quando o programa precisa buscar ou alterar dados;
• Webhook serve para receber notificações rápidas sobre eventos.

Por exemplo, em um CRM, a API permite obter e editar informações do cliente, enquanto o webhook avisa sobre novos leads ou mudanças de status. Muitas vezes, o webhook envia apenas informações básicas (ID e tipo de evento), e o aplicativo recorre à API para obter detalhes.

Esse modelo evita consultas constantes e mantém a flexibilidade da API tradicional.

Quando usar webhook e quando usar API tradicional

Quando o webhook é mais indicado

O webhook é melhor quando o sistema precisa ser informado imediatamente sobre um evento, como:

• confirmação de pagamento;
• novo pedido criado;
• mudança no status de entrega;
• novo lead em CRM;
• upload de arquivo;
• publicação de código em repositório.

Nesses casos, consultas regulares à API geram tráfego desnecessário e o webhook elimina esse problema, facilitando a automação e integração ágil entre serviços.

Quando a API é preferível

A API tradicional é indicada quando o aplicativo deve buscar dados a qualquer momento, por exemplo:

• procurar informações;
• listar objetos;
• criar ou modificar registros;
• excluir dados;
• obter detalhes por ID;
• escolher livremente quando consultar o servidor.

O webhook não é projetado para essas tarefas, pois sua função é notificar sobre eventos e não fornecer acesso arbitrário sob demanda. O modelo mais comum combina ambos: o webhook avisa sobre uma mudança e o aplicativo consulta a API para obter detalhes.

Webhook, polling e WebSocket

O webhook não é o único método para receber atualizações de outro serviço. Dependendo da necessidade, podem ser utilizados polling e WebSocket:

• Polling: o aplicativo faz requisições periódicas ao servidor (por exemplo, a cada 10 segundos) para verificar se há novidades. É fácil de implementar, mas pode consumir recursos desnecessariamente.
• Webhook: não mantém conexão constante. O serviço envia uma requisição HTTP apenas quando um evento ocorre, ideal para integrações e automações.
• WebSocket: cria uma conexão bidirecional persistente entre cliente e servidor, permitindo troca de dados em tempo real. Indicado para chats, jogos online, plataformas de trading e outros casos que exigem comunicação contínua.

Para saber mais sobre conexões contínuas, confira WebSocket: guia completo para dados em tempo real na web.

A escolha depende do tipo de informação: use API para buscas sob demanda, webhook para reagir automaticamente a eventos e WebSocket para troca contínua de dados em tempo real.

Como configurar um webhook e pontos importantes

Criando o endpoint do webhook

Para funcionar, o sistema receptor precisa de um endpoint público, onde o serviço externo enviará as requisições HTTP.

O desenvolvedor cria um manipulador para processar os dados recebidos. Esse URL é configurado nas definições do serviço de origem. Exemplo:

https://example.com/webhooks/payment

O endpoint deve ser acessível pela internet e utilizar HTTPS. Para desenvolvimento local, podem ser usados túneis ou serviços de teste que fornecem endereços públicos temporários.

Verificação de autenticidade do webhook

Por ser um endpoint aberto, não se pode confiar em qualquer requisição recebida. Se alguém descobrir o endereço, pode tentar enviar eventos falsos. Por isso, muitos serviços assinam os webhooks com uma chave secreta.

O sistema receptor valida a assinatura recebida e só aceita o evento se ela for válida, garantindo que os dados vieram da fonte correta e não foram alterados durante o trajeto.

Adicionalmente, podem ser usados tokens secretos, verificação de conexão HTTPS e restrição de IPs, conforme suporte do serviço.

Redelivery e duplicidade de eventos

O webhook não garante que a requisição será processada com sucesso na primeira tentativa. O servidor pode estar indisponível, a conexão pode falhar ou o processamento pode demorar.

Por isso, muitos serviços implementam o mecanismo de retry: se o endpoint retornar erro ou não responder, a notificação é reenviada.

Isso pode gerar notificações duplicadas. O aplicativo deve identificar e ignorar eventos já processados, especialmente em operações críticas como pagamentos (para evitar cobranças ou envios duplicados).

O identificador do evento deve ser verificado antes de realizar qualquer ação, garantindo processamento idempotente.

Logs e códigos de resposta

Após processar o webhook, o servidor deve retornar um código HTTP indicando sucesso (intervalo 200). Em caso de erro, o serviço externo tentará novamente.

Evite executar operações demoradas diretamente no endpoint: registre rapidamente o evento, retorne o sucesso e processe o restante em uma fila de tarefas, se necessário.

É recomendável registrar o horário, tipo, identificador do evento e resultado do processamento. Isso facilita a identificação de problemas e a análise de motivos para redelivery.

Um webhook bem configurado não é apenas um URL para receber POSTs, mas uma integração robusta que considera autenticação, redelivery, duplicidade, erros e indisponibilidade temporária.

Conclusão

O webhook permite que sistemas comuniquem eventos automaticamente sem a necessidade de consultas constantes via API. É ideal para notificações de pagamento, integrações, automações e todos os processos que requerem resposta rápida a mudanças.

A principal diferença em relação à API tradicional está no fluxo de interação: na API, o cliente solicita dados; no webhook, o serviço envia notificações após eventos. As duas tecnologias são complementares e frequentemente usadas juntas.

Use API para buscas sob demanda, criação ou alteração de dados. Use webhook para reagir automaticamente a eventos. Para comunicação bidirecional contínua em tempo real, prefira WebSocket.

Ao implementar um webhook, considere não apenas o envio da requisição HTTP, mas também segurança, verificação de assinatura, redelivery, prevenção de duplicidade e tratamento adequado de erros. Esses detalhes fazem de um endpoint de webhook uma integração confiável entre serviços.