Webhooks são a espinha dorsal da automação de pagamentos. Mas construir um sistema confiável vai muito além do "POST /webhook".
Os 5 pilares de um webhook robusto
1. Idempotência
Sempre considere que o mesmo evento pode chegar mais de uma vez. Use um identificador único (como o ID da transação) e mantenha um registro dos eventos já processados.
async function handleWebhook(payload: WebhookPayload) {
const exists = await db.events.findOne({ id: payload.id })
if (exists) return { status: 'already_processed' }await db.events.insertOne({ id: payload.id, ...payload }) await processPayment(payload) } ```
2. Validação de assinatura
Todo webhook precisa ser assinado pelo provedor. Valide a assinatura HMAC antes de qualquer processamento.
3. Resposta rápida
Responda 200 OK em até 5 segundos. Processe a lógica de negócio em background usando filas (SQS, Bull, etc).
4. Retry com backoff
Se o processamento falhar, garanta que o sistema tente novamente com intervalos crescentes: 30s, 2min, 10min, 1h.
5. Observabilidade
Monitore latência, taxa de sucesso e eventos perdidos. Use ferramentas como DataDog, NewRelic ou Grafana.
O diferencial Pixis
Na Pixis, implementamos validação ativa: cada webhook enviado é confirmado pelo seu sistema e, em caso de falha, automaticamente reenviado. Isso elimina a perda de pagamentos por falhas pontuais de rede.