Webhook: o que é, como funciona e quando usar

O cliente pagou o Pix às 10h02. Às 10h40 ele liga perguntando por que o pedido ainda aparece como "aguardando pagamento". Do outro lado, alguém do financeiro abre o painel do banco, confere o comprovante e libera o pedido à mão. Na semana seguinte, o mesmo pagamento aparece duas vezes no sistema e o estoque baixa em dobro.

Os dois problemas têm a mesma origem: o sistema da empresa não fica sabendo, na hora certa e uma única vez, que algo aconteceu em outro sistema. Ou ele pergunta tarde demais, ou recebe a notícia e não sabe lidar com a repetição.

Webhook é o mecanismo mais comum para resolver isso: um aviso automático que um sistema envia a outro no exato momento em que algo acontece, como um pagamento confirmado ou uma entrega concluída. Este texto explica como ele funciona, quando ele é a escolha certa e o que precisa estar desenhado para que nenhum evento se perca no caminho.

Webhook em uma frase, com exemplo do dia a dia

Webhook é um aviso automático que um sistema envia para outro, pela internet, no momento em que um evento acontece.

Em vez de o seu sistema perguntar ao banco a cada poucos minutos "esse pagamento já caiu?", o banco avisa o seu sistema assim que o pagamento é confirmado. O aviso é uma requisição HTTP enviada para um endereço que você cadastrou previamente (a URL do webhook), com os dados do evento no corpo da mensagem, normalmente em JSON.

A comparação mais próxima do dia a dia é a diferença entre ligar para a transportadora todo dia perguntando se a carga saiu e cadastrar o seu celular para receber uma mensagem quando ela sair. No segundo caso, você não gasta esforço perguntando, e fica sabendo assim que acontece.

Na prática, um webhook tem quatro peças:

• O evento: "pagamento aprovado", "nota autorizada", "entrega concluída".
• Quem envia: o sistema onde o evento acontece (gateway de pagamento, plataforma de loja, transportadora, ERP).
• Quem recebe: um endereço no seu sistema preparado para receber aquele aviso.
• O conteúdo: identificador do evento, tipo, data e os dados necessários (ou o identificador para buscá-los).

Webhook não é um produto nem uma ferramenta. É um padrão de comunicação oferecido por boa parte das plataformas de pagamento, loja virtual, logística e atendimento. Ferramentas de automação também recebem webhooks, como mostramos em Zapier, Make ou n8n. Outros textos sobre o tema estão na categoria Integrações e APIs.

Webhook x consulta periódica (polling)

A alternativa ao webhook é a consulta periódica, chamada de polling: o seu sistema pergunta ao outro, em intervalos fixos, se há novidade. As duas abordagens funcionam; o que muda é onde fica o custo e o atraso.

O ponto que costuma passar despercebido: webhook sozinho não garante que você recebeu tudo. Ele é rápido, mas depende de o seu endereço estar no ar e responder corretamente no momento do envio. Por isso, nas integrações bem feitas, os dois convivem: o webhook traz o evento na hora, e uma consulta periódica, mais espaçada, confere se algo escapou.

Exemplos de uso: pagamentos, pedidos, entregas

Pagamento aprovado

É o caso mais clássico. O gateway de pagamento ou o banco avisa que o Pix foi recebido, que o boleto foi compensado ou que o cartão passou pelo antifraude. O seu sistema marca o pedido como pago, libera a separação e envia a confirmação ao cliente. Sem webhook, essa liberação espera a próxima consulta ou a conferência manual do financeiro.

Também chegam por webhook os eventos ruins: pagamento recusado, estorno, contestação de cartão (chargeback). Esses são os que mais fazem falta quando ninguém os trata, porque o pedido segue como pago depois de o dinheiro ter voltado.

Pedido faturado

Quando o ERP emite a nota fiscal, ele pode avisar a loja virtual, o portal do cliente ou o marketplace de que o pedido foi faturado, enviando a chave de acesso e o link para o XML. O cliente recebe a nota sem que ninguém copie e cole nada. É um dos trechos centrais de qualquer projeto de integração com o ERP.

Entrega concluída

Transportadoras e plataformas de frete costumam notificar cada mudança de status: coletado, em trânsito, saiu para entrega, entregue, tentativa sem sucesso. Com isso, o seu sistema atualiza o pedido, dispara a mensagem ao cliente e, no caso de "entregue", pode iniciar o prazo de devolução ou a pesquisa de satisfação.

A regra para decidir é simples: se alguém da sua equipe hoje fica atualizando uma tela para saber se algo aconteceu, aquele evento é candidato a webhook.

O que acontece quando o webhook falha

O sistema de origem envia o aviso. Se o seu endereço responde com sucesso, o envio está concluído. Se não responde, demora demais ou devolve erro, a maioria das plataformas tenta de novo algumas vezes, com intervalos crescentes. Quantas vezes e por quanto tempo varia de fornecedor para fornecedor, e essa informação precisa ser lida na documentação de cada um antes de desenhar a integração.

As falhas mais comuns no lado de quem recebe:

• Servidor fora do ar durante uma publicação de versão ou uma manutenção.
• Processamento pesado dentro do recebimento. O seu sistema tenta gravar o pedido, baixar estoque e emitir nota antes de responder, estoura o tempo limite e o remetente considera que falhou, mesmo que o trabalho tenha sido feito.
• Erro de dado: produto não cadastrado, cliente com documento inválido.
• Certificado HTTPS vencido ou mudança de endereço sem atualizar o cadastro do webhook.

O desenho que evita a maior parte disso tem três partes:

1. Receber, gravar e responder rápido. O endereço do webhook só valida a mensagem, grava o evento numa fila ou tabela e responde que recebeu. O processamento acontece depois, separado.
2. Fila de exceções com dono. Evento que não pôde ser processado vai para uma lista com o motivo em linguagem legível e um botão para reprocessar depois da correção.
3. Conciliação periódica. Uma rotina compara, por exemplo, os pagamentos confirmados no gateway com os pedidos marcados como pagos no seu sistema. O que estiver diferente vira alerta.

Se a sua integração não tem nenhuma dessas três partes, ela depende de o webhook nunca falhar, e isso não existe.

Reenvio, duplicidade e ordem dos eventos

Retentativa resolve a perda, mas cria dois efeitos colaterais que precisam ser tratados de propósito.

Duplicidade

Se o seu sistema processou o evento mas a resposta não chegou ao remetente a tempo, ele reenvia. Do seu lado, o mesmo "pagamento aprovado" chega duas vezes. Sem proteção, o pedido é liberado duas vezes, o estoque baixa em dobro ou o cliente recebe duas mensagens.

A defesa é a idempotência: processar a mesma mensagem várias vezes tem o mesmo efeito que processá-la uma vez. Na prática, o sistema guarda o identificador de cada evento recebido e, antes de processar, verifica se já viu aquele identificador. Se já viu, responde que recebeu e não faz mais nada.

Ordem dos eventos

Webhooks não chegam necessariamente na ordem em que os eventos aconteceram. Um "entregue" pode chegar antes de um "saiu para entrega" que ficou preso numa retentativa. Se o seu sistema simplesmente grava o último status recebido, o pedido volta de "entregue" para "em trânsito".

Duas formas de tratar:

• Comparar data ou versão do evento: cada aviso carrega a data em que aconteceu na origem; aviso mais antigo do que o estado atual é registrado, mas não sobrescreve.
• Usar o webhook só como gatilho: ao receber o aviso, o seu sistema consulta a API de origem para buscar o estado atual daquele pedido. Assim, a ordem de chegada deixa de importar, porque a fonte sempre devolve o estado mais recente.

Checklist de recebimento confiável

• O endereço responde rápido e processa depois, fora do recebimento.
• Cada evento tem identificador único, e o sistema ignora repetidos.
• Eventos fora de ordem não sobrescrevem um estado mais novo.
• Erros vão para uma fila de exceções com motivo e opção de reprocessar.
• Uma conciliação periódica compara a origem com o seu sistema.
• Há alerta quando os avisos param de chegar por tempo fora do normal.
• O cadastro do webhook (endereço, eventos assinados, credenciais) está documentado.

O sexto item merece destaque: o silêncio também é um sinal. Se a loja vende todo dia e nenhum aviso de pagamento chega há horas, provavelmente algo quebrou, e é melhor descobrir pelo alerta do que pelo cliente.

Segurança: como validar quem enviou

O endereço do webhook precisa ser público para que o outro sistema consiga chamá-lo. Isso significa que qualquer pessoa que descubra o endereço pode enviar uma mensagem dizendo "pagamento aprovado". Se o seu sistema acredita em qualquer aviso, ele libera pedido não pago.

As proteções mais usadas, em geral combinadas:

• Assinatura da mensagem. O remetente calcula uma assinatura do conteúdo com uma chave secreta compartilhada (o método mais comum é o HMAC) e a envia no cabeçalho. O seu sistema recalcula com a mesma chave e descarta a mensagem se não bater.
• Proteção contra reenvio malicioso. A assinatura inclui a data do envio, e mensagens antigas demais são recusadas, para que alguém que capturou um aviso legítimo não consiga reenviá-lo mais tarde.
• Confirmação na fonte. Para eventos que mexem com dinheiro, o seu sistema consulta a API do gateway e confirma o status antes de liberar o pedido.
• HTTPS obrigatório, para que o conteúdo não trafegue aberto.
• Restrição por origem, quando o fornecedor publica os endereços de onde envia os avisos.

Também vale lembrar que webhooks de pedido e pagamento carregam dados pessoais. Pelo princípio da necessidade da LGPD, logs e filas de exceção não devem guardar mais dados pessoais do que o necessário, e o acesso a eles precisa ser restrito. Os erros mais frequentes nessa área, com e sem webhook, estão em segurança de APIs: os erros mais comuns.

Quando o webhook não é a melhor escolha

Webhook é a escolha natural quando a origem oferece o recurso e o evento precisa ser tratado rápido. Em alguns cenários, outro caminho funciona melhor:

• A origem não oferece webhook. Muitos ERPs e sistemas mais antigos não enviam avisos. Aí a saída é a consulta periódica do que mudou desde a última leitura.
• O dado muda o tempo todo e o que importa é o estado final. Saldo de estoque de um catálogo grande, por exemplo, às vezes é melhor sincronizado em lotes curtos do que com um aviso por movimentação.
• Carga em massa. Importar a tabela de preços inteira ou o histórico de pedidos é trabalho para exportação em lote, não para milhares de avisos.
• O seu lado não consegue expor um endereço público confiável, por restrições de rede ou de infraestrutura. Nesse caso, a consulta periódica ou uma fila intermediária resolve.
• A urgência é baixa. Se o relatório é fechado uma vez por dia, uma rotina noturna é mais simples de manter.

E o caminho inverso: se a sua empresa é quem fornece dados para parceiros e clientes, oferecer webhooks é uma forma de poupar o parceiro de consultar a sua API o tempo todo. Isso envolve cadastro de endereços, assinatura, retentativa e painel de entregas, temas tratados em como criar uma API para parceiros e clientes integrarem.

Critérios para decidir entre webhook, consulta ou os dois

Antes de pedir uma integração, responda por escrito:

1. Quais eventos importam e o que precisa acontecer quando cada um ocorre.
2. Qual o atraso aceitável para cada um: segundos, minutos ou o dia seguinte.
3. A origem oferece webhook para esses eventos? Com assinatura? Com retentativa?
4. Qual o volume esperado em dia normal e em pico.
5. O que acontece se um evento se perder: incômodo, prejuízo ou problema fiscal.
6. Quem vai olhar a fila de exceções e com que frequência.

Se o atraso aceitável é curto e a origem oferece webhook, use webhook com conciliação. Se a origem não oferece, use consulta do que mudou. Se perder um evento gera prejuízo, use os dois, sempre.

Perguntas frequentes

Qual a diferença entre API e webhook?

Numa API, o seu sistema faz uma chamada e pede uma informação quando precisa dela. No webhook, a direção se inverte: o outro sistema chama o seu, por conta própria, assim que um evento acontece. Os dois se completam, e é comum usar o webhook como aviso e a API para confirmar o estado atual na origem.

Webhook é seguro?

É seguro quando o recebimento é bem desenhado. Como o endereço do webhook é público, o sistema precisa validar a assinatura da mensagem com uma chave secreta, recusar avisos antigos demais, exigir HTTPS e, em eventos que envolvem dinheiro, confirmar o status na API de origem antes de agir. Sem essas proteções, qualquer pessoa poderia forjar um aviso.

Preciso de um programador para usar webhook?

Para fluxos simples, nem sempre: ferramentas de automação como Zapier, Make e n8n recebem webhooks e repassam os dados para outros aplicativos. Quando o webhook mexe com pagamento, estoque ou nota fiscal, porém, é preciso desenvolvimento para garantir idempotência, fila de exceções, validação de assinatura e conciliação, e isso pede alguém técnico.

O que é URL de webhook?

URL de webhook é o endereço no seu sistema, cadastrado previamente na plataforma de origem, para onde ela envia os avisos de eventos. Esse endereço precisa estar sempre disponível na internet, usar HTTPS, responder rápido e validar quem enviou cada mensagem. Se a URL muda ou o certificado vence sem atualizar o cadastro, os avisos deixam de chegar.

Como a Pervian Tech trabalha integrações por eventos

Na Pervian Tech, uma integração por eventos começa pelo diagnóstico: quais sistemas estão envolvidos, que avisos cada um consegue enviar, quais eventos a operação hoje confere na mão e o que acontece quando um deles se perde. A partir daí desenhamos o fluxo sob medida, com recebimento rápido, idempotência, validação de assinatura, fila de exceções e conciliação desde a primeira versão. Esse desenho faz parte do nosso trabalho de arquitetura de software e dos projetos de integração de sistemas.

O diagnóstico inicial é gratuito, e o cronograma é definido depois dele, porque depende do número de sistemas e de eventos envolvidos. O investimento é sob consulta. Se a sua equipe ainda descobre pagamentos e entregas atualizando tela, conte como funciona hoje.