O que é webhook: definição, exemplo e cuidados

O que é webhook, em palavras simples?

Webhook é um endereço na internet que o seu sistema deixa aberto para receber avisos de outro sistema. Quando algo acontece lá (um pagamento aprovado, uma venda nova, um cadastro), o outro sistema manda uma mensagem curta para esse endereço, e o seu sistema reage sozinho, sem ninguém conferir extrato.

Pense num porteiro que interfona quando a encomenda chega, em vez de você descer de hora em hora pra conferir. Tecnicamente, o aviso é uma chamada HTTP, o mesmo tipo de requisição que o navegador faz ao abrir um site, e o endereço que recebe se chama endpoint.

Como funciona um webhook no dia a dia de uma empresa?

O exemplo mais comum é o Pix. A loja gera uma cobrança, o cliente paga pelo app do banco e o banco ou o gateway avisa o sistema da loja pelo webhook. O sistema confere o aviso, marca o pedido como pago e dispara o que vem depois: e-mail, nota fiscal, liberação do acesso ou separação no estoque.

• Aviso. O seu sistema cadastra um endereço no provedor. O cliente paga e o provedor chama esse endereço com cobrança, valor e um identificador único do evento.
• Confirmação. O seu sistema responde "recebi" (código HTTP 200) em poucos segundos. Sem resposta, o provedor entende que falhou e tenta de novo.

Na especificação da API Pix do Banco Central, versão 2.10.0 lida em outubro de 2026, o webhook é cadastrado por chave Pix e só notifica Pix ligados a um txid, o identificador da cobrança. O prazo do aviso fica a cargo de cada instituição, que pode agrupar vários Pix numa chamada. O passo a passo está no guia como integrar Pix no sistema.

Na Velify, cada venda do Mercado Livre entra por webhook no painel. No Mindbot, o webhook da BuckPay confirma o Pix e o bot do Telegram faz a entrega.

Qual a diferença entre webhook e API?

API é a porta que você usa para perguntar ou pedir algo a outro sistema; webhook é o outro sistema batendo na sua porta para avisar. Na consulta pela API, chamada de polling quando se repete de tempos em tempos, quem toma a iniciativa é você. No webhook, é o provedor. Os dois se completam.

Sistema que lida com dinheiro usa os dois: webhook para reagir na hora e consulta pela API como plano B. A documentação de webhooks do Mercado Pago orienta, depois de receber a notificação, buscar os dados completos do pagamento na API.

O que pode dar errado com um webhook?

Quatro coisas: o aviso se perde, chega duplicado, chega fora de ordem ou é falso. Todas aparecem quando o volume cresce ou o servidor cai por alguns minutos, e o prejuízo vai de pedido travado a produto entregue sem pagamento.

• Aviso perdido. O servidor estava fora ou demorou, e o provedor desistiu. O GitHub, por exemplo, considera falha a entrega sem resposta em 10 segundos.
• Aviso duplicado. A documentação da Stripe avisa que o mesmo evento pode chegar mais de uma vez. Sem proteção, saem duas notas pra mesma venda.
• Fora de ordem. A Stripe também não garante a ordem de entrega. Se o estorno chega antes da aprovação, um sistema ingênuo marca como pago um pedido devolvido.
• Aviso falso. O endereço é público. Se o sistema aceita qualquer chamada, alguém pode mandar um "pagamento aprovado" inventado e levar o produto.

Quais cuidados um webhook bem feito precisa ter?

Cinco cuidados resolvem os quatro problemas: aceitar reenvio, processar cada evento uma vez só, conferir a assinatura de quem enviou, responder rápido e trabalhar em fila, e rodar uma conferência periódica. Todos estão nas documentações oficiais dos provedores e cabem em qualquer integração séria.

• Reenvio. Na Stripe, as novas tentativas duram até três dias em produção; no Mercado Pago, acontecem a cada 15 minutos, com intervalo maior depois da terceira.
• Idempotência. O mesmo aviso, recebido duas ou dez vezes, produz efeito uma vez só. O sistema guarda o identificador de cada evento e ignora o que já processou.
• Assinatura. O provedor assina cada aviso com uma chave secreta que só ele e você conhecem, e o sistema confere antes de agir. No Pix, a especificação usa mTLS, em que os dois lados apresentam certificado digital.
• Fila. O endereço responde "recebi" na hora e deixa nota, e-mail e estoque para uma fila de tarefas. GitHub e Stripe recomendam isso, porque quem processa antes de responder estoura o prazo.
• Conferência. Uma rotina diária compara o que o provedor recebeu com o que o seu sistema registrou. É ela que encontra o aviso perdido.

Quando a sua empresa precisa de webhook e quanto isso pesa no projeto?

Você precisa de webhook sempre que um sistema seu depende de saber, sem atraso, de algo que aconteceu em outro: pagamento confirmado, venda num marketplace, assinatura cancelada. Se ninguém precisa reagir na hora, uma conferência diária pela API pode bastar, e se você usa uma plataforma pronta de loja ou checkout, ela já trata tudo isso.

Receber um aviso é pouco código; o trabalho está nos cuidados acima, nos testes de cada falha e no monitoramento. Quando o webhook liga sistemas próprios, gateways e ERPs, é trabalho de integração de APIs ou de gateways de pagamento. Na VTA, os projetos começam a partir de R$ 20 mil, com proposta fechada de escopo, prazo e preço e resposta no mesmo dia. Descreva o cenário na página de orçamento.

Perguntas frequentes