Webhooks: o que é? Em termos simples, um webhook é uma forma de um sistema enviar uma notificação HTTP para outro sistema assim que um evento acontece. Em vez de o seu aplicativo perguntar repetidamente se há novidades, o serviço de origem envia os dados para uma URL que você cadastrou.

A ideia parece pequena — receber uma requisição POST —, mas é a base de automações de pagamentos, e-commerce, CRM, deploys, notificações de e-mail e fluxos com IA. Para usar webhooks sem perder eventos, duplicar pedidos ou aceitar requisições falsas, você precisa entender não só a configuração da URL, mas também assinaturas, respostas HTTP, filas, idempotência e monitoramento.

Webhooks: o que é, exatamente?

Um webhook é um callback HTTP orientado a eventos. Você informa a um provedor uma URL pública, chamada de endpoint ou URL de callback, e escolhe quais eventos deseja acompanhar. Quando um desses eventos ocorre, o provedor faz uma requisição HTTP — normalmente POST — para a sua URL com um payload, frequentemente em JSON.

O GitHub, por exemplo, permite assinar eventos como push de código, abertura de pull request ou criação de issue e entrega uma requisição à URL configurada quando o evento ocorre. A Stripe usa endpoints de webhook para avisar sobre eventos de pagamento que podem ocorrer fora do fluxo imediato do checkout, como confirmação de pagamento, disputa ou renovação de cobrança. (docs.github.com)

Pense na diferença assim:

API consultada (polling): seu sistema pergunta: “houve um pagamento novo?” a cada minuto.
Webhook: o provedor avisa: “o pagamento pi_... foi confirmado” no momento em que registra o evento.

Isso não torna uma API menos importante. Em integrações robustas, os dois mecanismos podem coexistir: o webhook dá rapidez; a API permite consultar detalhes, reconciliar falhas ou recuperar dados históricos.

A anatomia de uma entrega

Uma entrega de webhook costuma ter cinco peças:

Evento: o fato que disparou a notificação, como push, invoice.paid ou order.created.
Endpoint: a URL HTTPS do destinatário, como https://app.exemplo.com/webhooks/github.
Método e cabeçalhos HTTP: geralmente POST, Content-Type: application/json e cabeçalhos próprios do provedor.
Payload: os dados do evento, quase sempre JSON.
Resposta do receptor: seu servidor devolve um status HTTP, normalmente um 2xx, para indicar que recebeu a entrega.

O formato não é universal. Cada fornecedor define nomes de eventos, campos, cabeçalhos de autenticação, regras de repetição e limites de tamanho. O CloudEvents é uma especificação que busca padronizar a descrição de dados de eventos entre serviços, mas você não deve presumir que todo webhook use CloudEvents. (cloudevents.io)

Como um webhook funciona passo a passo

O fluxo técnico é direto, embora a operação por trás dele possa exigir cuidado:

Você cria um endpoint em seu aplicativo, por exemplo POST /webhooks/github.
Publica esse endpoint na internet usando HTTPS.
Cadastra a URL no painel ou API do serviço de origem.
Seleciona os eventos que devem gerar chamadas.
O evento acontece no serviço de origem.
O serviço faz uma requisição HTTP ao seu endpoint.
Seu endpoint valida a origem e registra ou enfileira o trabalho.
Seu endpoint retorna rapidamente uma resposta 2xx.
Um processo posterior executa a ação: enviar uma mensagem, atualizar um CRM, liberar acesso, iniciar um deploy ou gerar uma tarefa para IA.

Um payload fictício de pedido poderia ser parecido com este:

{
  "id": "evt_01HXYZ",
  "type": "order.created",
  "created_at": "2025-01-15T14:32:10Z",
  "data": {
    "order_id": "ord_8421",
    "customer_email": "ana@exemplo.com",
    "total": 129.90,
    "currency": "BRL"
  }
}

O payload informa o que aconteceu; ele não é necessariamente a fonte definitiva de todos os dados. Em eventos críticos, é comum usar o identificador recebido — como order_id ou event.id — para consultar a API do fornecedor e confirmar o estado atual antes de fazer uma ação irreversível.

Webhook, API, polling e WebSocket: qual é a diferença?

Os termos aparecem juntos, mas resolvem problemas diferentes.

Webhook versus API

Uma API é uma interface que seu aplicativo chama quando precisa ler ou alterar algo. Você usa uma chamada como GET /orders/8421 ou POST /messages. Um webhook faz o movimento oposto: o fornecedor inicia uma chamada para o seu aplicativo quando algo muda.

Na prática, uma integração madura usa os dois lados. A API cria ou consulta recursos; o webhook notifica mudanças assíncronas. Um checkout pode criar uma cobrança por API e, depois, receber a confirmação final por webhook, pois o pagamento pode depender de processamento bancário, autenticação adicional ou outras etapas externas.

Webhook versus polling

No polling, seu sistema consulta uma API em intervalos definidos. Isso pode introduzir atraso e gerar consultas que não encontram novidades. Em um webhook, o envio é disparado pelo evento, sem que seu sistema precise verificar constantemente.

Mas webhook não significa garantia absoluta de processamento único e perfeito. A entrega pode falhar, ser repetida ou chegar fora de ordem. Por isso, polling ou consultas periódicas à API ainda podem servir como mecanismo de reconciliação em processos financeiros ou operacionais importantes.

Webhook versus WebSocket

WebSocket mantém uma conexão bidirecional aberta entre cliente e servidor, sendo útil para atualizações contínuas, chats e interfaces em tempo real. Webhook é uma requisição HTTP independente enviada quando um evento ocorre; não exige uma conexão permanente.

Para disparar uma automação quando uma compra foi paga, um webhook é normalmente o encaixe natural. Para atualizar um gráfico a cada segundo na tela de um usuário, WebSocket ou Server-Sent Events pode ser mais apropriado.

Casos de uso práticos de webhooks

Webhooks são úteis sempre que uma mudança em um sistema precisa disparar uma reação em outro. Alguns exemplos comuns:

Pagamentos: liberar uma assinatura após a confirmação de pagamento, tratar reembolsos e alertar sobre disputas.
E-commerce: criar um contato no CRM quando há pedido, atualizar estoque ou avisar a logística.
Git e CI/CD: iniciar testes quando há push, criar ambiente de preview após uma pull request ou abrir ticket após falha de deploy.
E-mail transacional: registrar entrega, bounce, denúncia de spam, abertura ou clique quando o provedor oferece esses eventos. Ao desenhar esses fluxos, consulte a documentação da API de e-mail do provedor para saber o esquema de eventos e o método de validação adotado.
CRM e marketing: sincronizar um novo lead, iniciar uma sequência de onboarding ou atualizar a pontuação de um contato.
Automação e IA: enviar uma transcrição recém-gerada para classificação, resumir um ticket novo ou encaminhar um formulário para um agente de IA.
Operações internas: abrir incidente quando uma métrica passa um limite, registrar uma aprovação ou notificar um canal da equipe.

A regra útil é: se a ação depende de uma mudança detectada por outro sistema, procure se ele oferece webhook antes de construir polling agressivo.

O que você precisa para receber um webhook

Receber um webhook não exige necessariamente uma infraestrutura complexa, mas há requisitos mínimos.

1. Uma URL pública e HTTPS

O serviço emissor precisa alcançar o seu endpoint. Um endereço como http://localhost:3000/webhooks/github funciona apenas na sua máquina e não é acessível diretamente pela maioria dos provedores externos.

Em produção, use uma URL HTTPS pública, como:

https://api.suaempresa.com/webhooks/github

Durante o desenvolvimento local, ferramentas de túnel podem expor temporariamente seu servidor local por uma URL pública. Elas ajudam a testar, mas não substituem uma configuração estável de produção.

2. Uma rota que aceite o método correto

A documentação do fornecedor informa o método usado. Muitos webhooks enviam POST, mas isso não deve ser presumido. O nó Webhook do n8n, por exemplo, oferece suporte a métodos HTTP padrão, incluindo GET, POST, PUT, PATCH e DELETE; a escolha deve corresponder ao sistema emissor. (docs.n8n.io)

3. O segredo ou credencial de validação

Em geral, você cria um segredo ao configurar o webhook. O provedor usa esse segredo para assinar cada entrega, e seu servidor usa a mesma chave para verificar a assinatura.

Nunca deixe esse valor no código-fonte, em um repositório ou no navegador. Guarde-o como variável de ambiente ou em um gerenciador de segredos. A documentação do GitHub recomenda armazenar o token de segredo de modo seguro e validar a assinatura antes de processar a entrega. (docs.github.com)

4. Registro de eventos e respostas

Você precisa conseguir responder a perguntas básicas: qual evento chegou, em que horário, com qual identificador, que status HTTP seu endpoint retornou e se o processamento posterior terminou. Sem isso, um webhook que “não funcionou” vira um diagnóstico por tentativa e erro.

Como configurar um webhook sem errar

O painel muda de ferramenta para ferramenta, mas o procedimento é bastante consistente.

Passo 1: escolha eventos específicos

Selecione somente os eventos que seu sistema sabe tratar. Assinar todos os eventos “por segurança” aumenta tráfego, custo, ruído nos logs e risco de processar algo de modo imprevisto. O GitHub recomenda limitar as assinaturas aos eventos que você planeja manipular. (github.com)

Se você só precisa iniciar testes quando houver código novo, escolha o evento de push. Se precisa criar um fluxo para novos pedidos, escolha o evento de criação de pedido, não toda atualização possível de catálogo, estoque e cliente.

Passo 2: defina uma URL por integração ou por domínio de responsabilidade

Você pode usar uma rota por fornecedor:

/webhooks/github
/webhooks/stripe
/webhooks/email-provider

Esse desenho simplifica a validação, a rotação de segredos, o controle de permissões e os logs. Também evita que a lógica de um provedor dependa de cabeçalhos de outro.

Em alguns produtos, uma única URL pode receber vários tipos de evento. Isso é normal, desde que o código faça roteamento explícito pelo nome do evento e ignore com segurança tipos não suportados.

Passo 3: configure o segredo e guarde-o fora do código

Use um segredo aleatório gerado pelo fornecedor ou por um gerador criptograficamente seguro. Dê a ele um nome claro no seu ambiente, como:

GITHUB_WEBHOOK_SECRET=...

Se houver suspeita de exposição, rode o segredo no painel do fornecedor e atualize o valor no ambiente do endpoint. Planeje a rotação de forma a aceitar, temporariamente, o segredo anterior e o novo apenas se a documentação do fornecedor permitir essa estratégia.

Passo 4: responda rápido, processe depois

A entrega HTTP não deve esperar o envio de dezenas de e-mails, uma consulta lenta, uma chamada a modelo de IA ou uma operação de banco demorada. O GitHub recomenda que o servidor responda com 2XX dentro de 10 segundos; depois desse limite, ele encerra a conexão e considera a entrega falha. A própria recomendação é usar uma fila para processar payloads de modo assíncrono. (docs.github.com)

O padrão é:

receber → validar → persistir/enfileirar → responder 200/202 → processar em worker

O status 200 OK costuma comunicar que você recebeu e aceitou a entrega. 202 Accepted é apropriado quando o processamento foi aceito para execução assíncrona. O fornecedor pode ter exigências próprias, portanto consulte sua documentação para saber quais respostas ele considera bem-sucedidas.

Exemplo completo: receber um webhook do GitHub com Node.js

Este exemplo mostra a estrutura essencial de um endpoint Express para receber eventos do GitHub. O GitHub envia uma assinatura HMAC SHA-256 no cabeçalho X-Hub-Signature-256 quando um segredo é configurado. O valor tem o prefixo sha256= e deve ser comparado com uma assinatura calculada sobre o corpo bruto da requisição. (docs.github.com)

1. Instale o Express

npm install express

2. Crie o endpoint

import express from "express";
import crypto from "node:crypto";

const app = express();
const secret = process.env.GITHUB_WEBHOOK_SECRET;

if (!secret) {
  throw new Error("Defina GITHUB_WEBHOOK_SECRET antes de iniciar o servidor.");
}

function isValidGitHubSignature(rawBody, signatureHeader) {
  if (!signatureHeader) return false;

  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const expectedBuffer = Buffer.from(expected, "utf8");
  const receivedBuffer = Buffer.from(signatureHeader, "utf8");

  if (expectedBuffer.length !== receivedBuffer.length) return false;

  return crypto.timingSafeEqual(expectedBuffer, receivedBuffer);
}

app.post(
  "/webhooks/github",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.get("X-Hub-Signature-256");

    if (!isValidGitHubSignature(req.body, signature)) {
      return res.status(401).send("Assinatura inválida");
    }

    const eventName = req.get("X-GitHub-Event");
    const deliveryId = req.get("X-GitHub-Delivery");
    const payload = JSON.parse(req.body.toString("utf8"));

    // Em produção: grave deliveryId e o payload em banco/fila antes de responder.
    console.log({ eventName, deliveryId, repository: payload.repository?.full_name });

    // Exemplo: aceite agora; processe o trabalho pesado em segundo plano.
    return res.status(202).json({ received: true });
  }
);

app.listen(3000, () => {
  console.log("Ouvindo em http://localhost:3000");
});

Há três detalhes importantes nesse código:

express.raw() preserva o corpo original em bytes. Não calcule a assinatura sobre um objeto JSON reserializado, porque espaços, ordem de campos e codificação podem mudar o conteúdo assinado.
crypto.timingSafeEqual() evita uma comparação simples de strings que pode vazar diferenças de tempo em certos cenários.
O código devolve 202 depois de validar e registrar a entrega. Em uma aplicação real, a etapa seguinte deve ir para uma fila, tabela de eventos ou outro mecanismo durável.

Os nomes X-Hub-Signature-256, X-GitHub-Event e X-GitHub-Delivery são específicos do GitHub. Outros fornecedores usam cabeçalhos e algoritmos diferentes. A Stripe, por exemplo, usa o cabeçalho Stripe-Signature e recomenda verificar a assinatura com suas bibliotecas oficiais ou seguindo o método documentado. (docs.stripe.com)

3. Cadastre o webhook no GitHub

No repositório, abra as configurações de Webhooks e adicione a URL pública do endpoint. Informe o mesmo segredo que está em GITHUB_WEBHOOK_SECRET, escolha application/json como formato de conteúdo quando essa for a opção desejada e marque apenas os eventos que seu código implementa.

Para o exemplo, selecione o evento de push. Ao fazer um push no repositório, o GitHub enviará uma entrega à rota configurada. Os detalhes de entrega mostram cabeçalhos, payload, horário e a resposta recebida do seu servidor, o que ajuda a confirmar a configuração. (docs.github.com)

Como saber que funcionou

Você deve ver, no mínimo, quatro sinais:

O painel do GitHub registra a entrega do evento.
A entrega mostra um status HTTP 2xx.
O log do seu endpoint contém eventName: "push" e um deliveryId.
O item aparece na fila, tabela ou processo posterior que executará a automação.

Não considere “funcionou” apenas porque o endpoint retornou 200. Um 2xx confirma o recebimento pelo seu serviço; não comprova que a lógica de negócio terminou corretamente. A confirmação final deve incluir o estado do processamento assíncrono.

Assinatura, autenticação e segurança de webhooks

Uma URL pública pode receber tráfego de qualquer origem. Se seu endpoint aceitar qualquer POST com JSON, alguém pode tentar simular um pagamento, disparar automações internas ou consumir recursos do servidor. Validar a origem é obrigatório para eventos com qualquer impacto operacional.

Valide a assinatura antes de agir

O modelo mais comum é uma assinatura HMAC. O fornecedor e você conhecem um segredo. O fornecedor calcula uma assinatura a partir do payload e a envia em um cabeçalho; seu servidor calcula novamente e compara os valores.

A validação responde a duas perguntas: a entrega foi gerada por quem conhece o segredo? O conteúdo foi alterado depois de assinado? No caso do GitHub, a documentação explica que a verificação ajuda a garantir que a entrega veio do GitHub e não foi adulterada. (docs.github.com)

Não invente o algoritmo. Use exatamente o que a documentação do fornecedor define, incluindo corpo bruto, timestamp, versão da assinatura, prefixo e codificação. A Twilio, por exemplo, usa um cabeçalho X-Twilio-Signature e monta a validação com a URL exata e parâmetros enviados; copiar uma estratégia feita para GitHub não funcionará para ela. (twilio.com)

Use HTTPS e proteja segredos

HTTPS protege o tráfego em trânsito contra observação e alteração por terceiros no caminho. Também use certificados válidos e desative endpoints HTTP sem TLS quando o fornecedor oferecer HTTPS.

Segredos de webhook são credenciais. Coloque-os em variáveis de ambiente, cofre de segredos ou configuração protegida da plataforma. Restrinja quem pode ler logs: payloads podem conter e-mail, endereço, identificadores de cliente e outros dados sensíveis.

Rejeite payloads suspeitos e limite impacto

Mesmo uma assinatura válida não transforma o payload em dado seguro para qualquer uso. Valide campos obrigatórios, tipos, tamanhos e regras de negócio. Nunca use diretamente um valor recebido para montar consulta SQL, caminho de arquivo, comando de shell ou URL interna.

Também imponha limites de tamanho do corpo, rate limiting compatível com o tráfego esperado e controle de acesso à infraestrutura. A orientação geral da OWASP para webhooks inclui autenticação, verificação de assinatura, proteção contra replay, validação de entrada, HTTPS e monitoramento. (github.com)

Previna replay quando o fornecedor oferecer timestamp

Um ataque de replay reutiliza uma requisição válida capturada anteriormente. Alguns provedores incluem timestamp na assinatura para que você rejeite eventos antigos fora de uma janela aceitável. Quando esse recurso existir, valide o timestamp conforme a documentação do fornecedor e mantenha registro de IDs de evento já processados.

Não aplique uma janela inventada. Use a regra especificada pelo provedor, pois o formato e a tolerância de relógio variam.

Duplicatas, falhas e eventos fora de ordem

A pergunta mais importante em produção não é “o webhook chega?”, mas “o que acontece se ele chegar duas vezes, atrasado ou na ordem errada?”.

Faça seu processamento ser idempotente

Idempotência significa que repetir a mesma entrega não muda o resultado final depois da primeira vez. Se o evento evt_01HXYZ for entregue duas vezes, seu sistema não deve enviar dois e-mails de boas-vindas, criar duas faturas ou creditar duas vezes uma conta.

A implementação mais simples é guardar um identificador de evento único em uma tabela com índice único. Antes de executar a ação, tente gravar o ID. Se ele já existir como processado, ignore a duplicata. Uma estrutura conceitual seria:

webhook_events
- provider
- event_id
- event_type
- received_at
- status
- payload

UNIQUE(provider, event_id)

A Stripe orienta que o processamento de eventos não entregues use marcações de estado para impedir duplicação, como verificar se o evento está sendo processado ou já foi processado antes de executar o trabalho. (docs.stripe.com)

Não dependa da ordem de chegada

Pode acontecer de um evento de atualização chegar antes do evento de criação, ou de uma nova tentativa de um evento antigo chegar depois de um evento mais novo. O seu código deve lidar com isso.

Boas respostas incluem buscar o estado atual pela API do fornecedor, usar timestamps ou versões quando disponíveis e modelar transições de estado válidas. Em pagamentos, por exemplo, não marque um pedido como “pago” apenas porque uma mensagem de interface chegou; use o evento e o estado oficial apropriados do provedor.

Planeje falhas de entrega e recuperação

Cada fornecedor tem sua política. O GitHub informa que não repete automaticamente entregas falhas para webhooks comuns e permite reentregar entregas recentes por uma janela limitada; a documentação atual indica três dias para a reentrega manual em GitHub.com. (docs.github.com)

Já outros serviços podem tentar novamente de forma automática. Isso significa que o seu endpoint precisa tratar repetição como comportamento normal, e não como exceção. Mantenha uma tela, log ou alerta para eventos que falharam permanentemente e um procedimento de recuperação por ID de evento.

Testes e depuração: como descobrir o que está errado

Grande parte dos problemas está entre a URL cadastrada e o código que interpreta a requisição. Teste em camadas, em vez de tentar diagnosticar tudo ao mesmo tempo.

Checklist de teste

Confirme que a URL cadastrada é pública e usa HTTPS.
Confirme que método, caminho e barra final da rota são exatamente os esperados.
Envie um evento de teste pelo painel do fornecedor, quando ele oferecer esse recurso.
Veja o status HTTP e o corpo da resposta no histórico de entregas.
Verifique os cabeçalhos recebidos, principalmente o nome do evento, ID de entrega e assinatura.
Teste a assinatura válida e uma assinatura deliberadamente inválida.
Reenvie o mesmo evento para confirmar que a idempotência funciona.
Simule indisponibilidade e confira como o provedor reporta ou repete a falha.

No GitHub, a área de entregas permite inspecionar os cabeçalhos, o payload, o horário e a resposta do servidor; isso é muito mais útil do que adivinhar o que foi enviado. (docs.github.com)

Erros comuns e correções

Erro: recebo 401 Assinatura inválida. Geralmente o segredo cadastrado não é o mesmo usado no ambiente, o cabeçalho está sendo lido com nome errado ou o JSON foi analisado antes da verificação e o corpo bruto se perdeu. Preserve o raw body e siga a documentação daquele fornecedor.

Erro: o fornecedor mostra timeout. Seu endpoint está fazendo trabalho lento antes de responder. Valide, grave ou enfileire o evento e retorne 2xx; deixe a ação pesada para um worker.

Erro: funciona em teste, mas não em produção. Pode ser que você tenha cadastrado uma URL de teste, deixado o workflow inativo, usado variável de ambiente diferente ou bloqueado a rota por firewall. No n8n, por exemplo, há URLs distintas para teste e produção: a URL de produção é registrada quando o workflow é publicado. (docs.n8n.io)

Erro: a automação executa duas vezes. Trate o ID da entrega como chave de idempotência e considere que retries fazem parte do funcionamento normal.

Erro: o evento não aparece. Confira se você assinou o tipo de evento certo, se o fato ocorreu no recurso correto e se o fornecedor registrou uma tentativa. O GitHub observa que entregas podem levar alguns minutos para aparecer no histórico e pode limitar temporariamente a taxa de entregas em picos. (docs.github.com)

Webhooks sem código: n8n e ferramentas de automação

Você não precisa construir um servidor Node.js para toda automação. Plataformas como n8n oferecem um nó Webhook que pode iniciar um workflow quando recebe uma chamada de outro serviço. Isso é útil para conectar sistemas que não têm uma integração pronta.

No n8n, o nó Webhook tem URLs separadas para teste e produção, aceita métodos HTTP padrão e pode responder imediatamente ou ao final do workflow. A documentação também informa um limite padrão de payload de 16 MB, configurável em instalações self-hosted por variável de ambiente. Esses detalhes são específicos do n8n, não uma regra universal de webhooks. (docs.n8n.io)

Mesmo em uma ferramenta visual, as regras fundamentais continuam valendo:

valide autenticação ou assinatura quando o emissor oferecer esse mecanismo;
responda antes de fluxos longos quando a política do emissor exigir rapidez;
registre o ID do evento para impedir duplicidade;
trate dados recebidos como entrada não confiável;
mantenha um caminho para reprocessar falhas.

Ferramentas de automação aceleram a entrega, mas não eliminam responsabilidade sobre segurança, custos de execução, dados pessoais e efeitos duplicados.

Um padrão de arquitetura que continua funcionando à medida que você cresce

Para um protótipo, validar e executar tudo na mesma rota pode bastar. Para processos importantes, adote uma separação simples entre recepção e processamento.

Provedor
  → endpoint HTTPS
  → validação de assinatura
  → banco/outbox ou fila durável
  → resposta HTTP 2xx
  → worker
  → ação de negócio
  → logs, métricas e alertas

Esse modelo reduz timeout, preserva a entrega mesmo se um serviço interno estiver lento e permite retentar o processamento sem pedir que o fornecedor reenvie o webhook. Também deixa mais claro onde algo falhou: na recepção, na validação, no enfileiramento ou na ação final.

Registre pelo menos o provedor, o ID do evento, o tipo, o horário de recebimento, o resultado da verificação, o status de processamento e um identificador de correlação. Mas evite registrar desnecessariamente dados pessoais completos ou segredos em logs.

Conclusão

Webhooks são notificações HTTP disparadas por eventos. Eles tornam integrações reativas: quando um pagamento confirma, um pedido nasce, um e-mail falha ou um push acontece, seu sistema recebe um aviso e pode agir sem fazer consultas constantes.

A implementação correta vai além de criar uma URL. Escolha eventos específicos, exponha um endpoint HTTPS, preserve o corpo bruto, valide a assinatura, responda rapidamente, trate duplicatas, aceite eventos fora de ordem e mantenha logs que permitam recuperar falhas. Se você seguir esse fluxo, webhooks deixam de ser uma “chamada misteriosa” e se tornam uma base confiável para automação de produto, marketing e operações.

FAQ

Webhook é uma API?

Não exatamente. API é a interface que seu aplicativo chama para consultar ou alterar recursos. Webhook é uma chamada iniciada pelo fornecedor para avisar seu aplicativo sobre um evento. As duas tecnologias são frequentemente usadas juntas.

Webhooks usam sempre POST?

Não. POST é muito comum, mas o método é definido pelo fornecedor. Confira a documentação do serviço que está enviando o evento e configure sua rota para aceitar o método correto.

É seguro aceitar qualquer webhook em uma URL pública?

Não. A URL precisa ser pública para receber a chamada, mas seu código deve validar assinatura, autenticação ou outro mecanismo definido pelo fornecedor. Também deve usar HTTPS, validar o payload e proteger segredos.

Por que recebi o mesmo webhook duas vezes?

Repetições podem ocorrer por retries após falha, timeout ou comportamento de entrega do fornecedor. Trate eventos como potencialmente duplicados e use um ID único do evento para tornar o processamento idempotente.

Como sei se meu webhook funcionou?

Verifique a entrega no painel do fornecedor, confirme que seu endpoint respondeu com 2xx, confira os logs com o ID do evento e valide que o processamento posterior terminou com sucesso. Uma resposta HTTP bem-sucedida, sozinha, não prova que a ação de negócio foi concluída.

Webhooks: o que é, como funciona e como implementar com segurança