Webhooks de pagamento: o guia para uma integração confiável

Se a cobrança é a pergunta, o webhook é a resposta: é por ele que o gateway avisa o seu sistema, em tempo real, que um pagamento foi confirmado, expirou ou falhou. Integrar webhooks bem é o que separa uma operação automatizada de uma cheia de conferências manuais. Este guia cobre as práticas que tornam essa integração confiável.

O que é um webhook

Um webhook é uma chamada HTTP que o gateway faz para uma URL sua sempre que um evento relevante acontece. Em vez de o seu sistema ficar perguntando "já pagou? já pagou?", o gateway empurra a informação assim que ela existe. É eficiente e quase instantâneo.

Um evento típico de pagamento confirmado traz o identificador da cobrança, o status e o valor — o suficiente para o seu sistema localizar o pedido e liberá-lo.

Os três pilares de um webhook confiável

1. Verificação de assinatura

Como a URL do seu webhook é pública, qualquer um poderia tentar enviar uma notificação falsa de "pagamento confirmado". Por isso, gateways sérios assinam cada notificação (em geral com HMAC). Seu servidor recalcula a assinatura com o segredo compartilhado e só aceita o evento se ela bater.

// pseudo-código de verificação HMAC
$assinaturaEsperada = hmac_sha256($corpoBruto, $segredo);
if (!hash_equals($assinaturaEsperada, $assinaturaRecebida)) {
    http_response(401); // rejeita
}

Nunca confie no conteúdo de um webhook sem validar a assinatura.

2. Idempotência

Por desenho, webhooks podem chegar mais de uma vez (reentregas, timeouts, retentativas). Se o seu sistema liberar o pedido a cada notificação, você corre o risco de entregar o mesmo produto duas vezes. A solução é idempotência: registre o identificador do evento e, se ele já foi processado, ignore com segurança.

if (jaProcessado($evento->id)) {
    http_response(200); // confirma sem reprocessar
    return;
}
processar($evento);
marcarProcessado($evento->id);

3. Resposta rápida e reentrega

Responda ao webhook com 2xx assim que registrar o evento, e faça o trabalho pesado de forma assíncrona. Se o seu endpoint demora ou devolve erro, um bom gateway reenfileira e reentrega a notificação com backoff — então o seu trabalho é apenas garantir que reentregas sejam tratadas de forma idempotente.

Checklist de produção

• Endpoint exclusivamente HTTPS.
• Assinatura verificada em toda requisição.
• Idempotência por identificador de evento.
• Resposta 2xx imediata + processamento assíncrono.
• Log de cada evento recebido (para auditoria e depuração).
• Consulta de status como rede de segurança, caso uma notificação se perca.
• Tolerância a eventos fora de ordem (um "pago" pode chegar antes de um "criado").

Erros comuns que custam caro

Os deslizes mais frequentes — e mais perigosos — em integrações de webhook são: aceitar notificações sem validar assinatura; tratar cada chamada como única (sem idempotência); fazer processamento lento dentro do request e estourar o timeout; e confiar 100% no webhook sem nenhuma consulta de reconciliação. Evitando esses quatro, você já está à frente da maioria.

Webhooks são a espinha dorsal de uma integração de pagamentos moderna. Bem feitos, eles tornam a confirmação invisível e instantânea; mal feitos, viram fonte de bugs difíceis de reproduzir. Vale investir para acertar desde o começo.

Perguntas frequentes