Webhook é uma requisição HTTP que o provedor envia para a sua aplicação quando algo acontece — no caso do Pix, principalmente quando uma cobrança é paga. É o mecanismo que transforma um pagamento em ação: liberar o acesso, despachar o pedido, emitir a nota.
O fluxo do evento
- A loja cadastra uma URL pública HTTPS.
- O pagamento é liquidado.
- O provedor envia POST com o payload do evento e um cabeçalho de assinatura.
- A aplicação valida a assinatura, responde 2xx e processa em segundo plano.
- Se a resposta falhar, o provedor reenvia com backoff.
Por que validar a assinatura
Uma URL de webhook é pública por definição. Sem validação, qualquer pessoa que descubra o endereço pode enviar um evento falso de pagamento aprovado. A validação recalcula um HMAC sobre o corpo bruto da requisição usando o segredo compartilhado e compara com o cabeçalho recebido, em comparação de tempo constante.
Valide sempre sobre o corpo bruto (raw body). Se o framework já converteu o JSON, a serialização pode diferir e a assinatura nunca vai bater.
Eventos duplicados e fora de ordem
Reenvio é parte do desenho: é assim que o sistema garante entrega. Sua aplicação precisa ser idempotente no consumo — guardar o identificador do evento já processado e ignorar repetição. Também assuma que a ordem não é garantida: verifique o status atual antes de regredir um pedido.
Responda rápido
Processar tudo antes de responder é a causa mais comum de reenvio desnecessário. Grave o evento, responda 2xx e execute o trabalho pesado depois.
Perguntas frequentes
- Posso usar http em vez de https no webhook?
- Não. O endpoint precisa ser HTTPS: o payload contém dados de pagamento.
- E se meu servidor cair?
- O provedor reenvia o evento com backoff. Ao voltar, a aplicação recebe o que perdeu — por isso o consumo precisa ser idempotente.