O que é webhook e como usar: exemplos com pagamentos e notificações

Atualizado em 3 de novembro de 2026 · Leitura de 5 min

Edson Feitosa de Oliveira Junior Fundador e Engenheiro Líder · PruPru Digital Services

Webhook é uma forma de um sistema avisar outro, automaticamente, que algo aconteceu. Em vez de a sua aplicação perguntar a cada minuto "o pagamento já foi aprovado?", o serviço de pagamentos envia uma requisição HTTP para um endereço da sua aplicação no momento em que o pagamento é aprovado. É o mecanismo por trás de muitas integrações do dia a dia: confirmação de Pix e cartão, mensagens recebidas em plataformas de atendimento, notificações de commits no GitHub e alertas de monitoramento.

Webhook ou consulta periódica

Em resumo: o webhook é uma API que você expõe para que outro sistema chame. Se ainda não está familiarizado com APIs, veja o que é uma API REST.

Como funciona na prática

Exemplo com pagamentos:

1. O cliente escolhe pagar com Pix ou cartão. Sua aplicação cria a cobrança no provedor de pagamentos.
2. Você cadastra, no painel do provedor, a URL do webhook, por exemplo https://api.seusite.com.br/webhooks/pagamentos.
3. Quando o pagamento é aprovado, o provedor envia um POST para essa URL com um JSON descrevendo o evento.
4. Sua aplicação valida a requisição, atualiza o pedido e responde rapidamente com status 200.

Um evento típico:

{
  "id": "evt_9f2c1",
  "type": "payment.approved",
  "created_at": "2026-11-02T14:03:22Z",
  "data": { "payment_id": "pay_771", "order_id": "8231", "amount": 149.90 }
}

O formato exato varia de provedor para provedor; consulte sempre a documentação. Para entender a estrutura, veja JSON para iniciantes. Sobre o lado do negócio, veja link de pagamento: como funciona.

Segurança: nunca confie cegamente

A URL do webhook é pública. Qualquer pessoa que a descubra pode enviar um "pagamento aprovado" falso. Por isso:

1. Valide a assinatura. A maioria dos provedores assina cada requisição com um segredo compartilhado (geralmente HMAC com SHA-256) e envia a assinatura em um cabeçalho. Sua aplicação recalcula a assinatura com o corpo bruto recebido e compara. Se não bater, rejeite.
2. Ou confirme na fonte. Quando possível, use o identificador recebido para consultar o status diretamente na API do provedor antes de liberar o pedido.
3. Use HTTPS sempre.
4. Guarde o segredo do webhook fora do código. Veja variáveis de ambiente e segredos.
5. Verifique o carimbo de tempo, se o provedor enviar, para rejeitar requisições antigas reenviadas por um atacante.

Exemplo de validação em Node.js:

import crypto from "node:crypto";

function assinaturaValida(corpoBruto, assinaturaRecebida, segredo) {
  const esperada = crypto.createHmac("sha256", segredo)
    .update(corpoBruto)
    .digest("hex");
  const a = Buffer.from(esperada);
  const b = Buffer.from(assinaturaRecebida || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

A comparação com timingSafeEqual evita ataques que medem o tempo de resposta. O cálculo deve usar o corpo bruto, exatamente como recebido, e não o JSON já convertido e reformatado.

Idempotência: o mesmo evento pode chegar mais de uma vez

Provedores reenviam o webhook quando não recebem uma resposta de sucesso, e às vezes enviam o mesmo evento duas vezes mesmo assim. Se a sua aplicação liberar o pedido a cada recebimento, o cliente pode receber o produto em dobro, ou o estoque pode ser baixado duas vezes.

A solução é guardar o identificador de cada evento processado e ignorar os repetidos:

1. Ao receber, verifique se o id do evento já foi registrado.
2. Se sim, responda 200 e não faça nada.
3. Se não, registre e processe.

Uma restrição de unicidade no banco de dados garante isso mesmo com requisições simultâneas.

Responda rápido e processe depois

Provedores esperam uma resposta em poucos segundos. Se o processamento for demorado (gerar nota, enviar e-mail, atualizar outros sistemas):

1. Valide e registre o evento.
2. Responda 200 imediatamente.
3. Processe em segundo plano, por meio de uma fila ou tarefa assíncrona.

Responda com erro (4xx ou 5xx) apenas quando quiser que o provedor tente de novo ou quando a requisição for inválida. Veja códigos de status HTTP.

Ordem dos eventos

Eventos podem chegar fora de ordem: um "pagamento estornado" antes do "pagamento aprovado", por exemplo. Use as datas do evento e o status atual consultado na API para decidir o que fazer, em vez de supor uma sequência.

Testando webhooks no desenvolvimento

O provedor precisa alcançar a sua aplicação, mas localhost não é acessível pela internet. Opções:

• Ferramentas de túnel, que criam um endereço público temporário apontando para a sua máquina.
• Ferramentas de linha de comando dos próprios provedores, que encaminham eventos de teste.
• Sites de inspeção de requisições, para ver exatamente o que o provedor envia.
• Ambiente de testes (sandbox) do provedor, que permite simular pagamentos sem dinheiro real.

Registre nos logs o recebimento de cada evento, com o identificador, mas sem dados sensíveis. Veja logs em produção.

Checklist de um webhook confiável

• URL com HTTPS e segredo de assinatura configurado.
• Assinatura validada com o corpo bruto.
• Eventos repetidos ignorados (idempotência).
• Resposta rápida e processamento em segundo plano.
• Estado atual confirmado na API quando houver dúvida.
• Logs e alerta para falhas de processamento.

Um webhook bem implementado é a diferença entre um sistema que confirma pagamentos sozinho e um que exige alguém conferindo extratos o dia inteiro.

Perguntas frequentes