# Webhook: o que é, como funciona e quando usar

> Entenda o que é webhook com exemplos de pagamento, pedido e entrega, a diferença para o polling e os cuidados para não perder nem duplicar eventos.

Fonte: https://pervian.tech/blog/webhook-o-que-e · Pervian Tech · publicado em 2026-10-01

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](https://pervian.tech/blog/zapier-make-ou-n8n). Outros textos sobre o tema estão na categoria [Integrações e APIs](https://pervian.tech/blog/categoria/integracoes).

## 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.

| Critério | Webhook | Consulta periódica (polling) |
|---|---|---|
| Quem toma a iniciativa | O sistema de origem avisa | O seu sistema pergunta |
| Atraso até saber do evento | Segundos, em condições normais | Até o próximo ciclo de consulta |
| Requisições desperdiçadas | Poucas: só há chamada quando há evento | Muitas: a maioria das consultas volta vazia |
| Limite de requisições da API | Raramente é problema | Aperta com volume alto ou ciclo curto |
| O que exige do seu lado | Endereço público, seguro e sempre disponível | Só um agendador que faz chamadas de saída |
| Risco principal | Perder aviso se o recebimento falhar | Saber tarde e estourar limite de API |
| Quando a origem não oferece | Não é opção | Sempre é opção |

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](https://pervian.tech/blog/integracao-com-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](https://pervian.tech/blog/como-integrar-seu-sistema-com-o-erp).

### Entrega concluída

[Transportadoras e plataformas de frete](https://pervian.tech/blog/integracao-com-transportadoras-e-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](https://pervian.tech/blog/ci-cd-para-gestores) 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](https://pervian.tech/blog/seguranca-de-apis-erros-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](https://pervian.tech/blog/filas-e-mensageria-quando-usar) 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](https://pervian.tech/blog/api-para-parceiros-e-clientes).

## 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](https://pervian.tech/servicos/arquitetura-de-software) e dos projetos de [integração de sistemas](https://pervian.tech/solucoes/integracao-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](https://pervian.tech/#contato).