Webhooks de Stripe: guia para no perder pagos en produccion

Los webhooks son la razon numero uno por la que una integracion de Stripe falla en produccion. Todo parece funcionar en pruebas. En produccion, pagos desaparecen silenciosamente.

Que son los webhooks

Cuando algo pasa en Stripe (pago aprobado, devolucion, suscripcion renovada), Stripe manda un mensaje HTTP a tu servidor. Tu sistema debe recibirlo, procesarlo y confirmar.

Si tu servidor no recibe o no procesa bien, pierdes la informacion.

Por que fallan silenciosamente

1. Tu servidor esta caido cuando llega el webhook. Stripe reintenta, pero si tu monitoreo no lo registra, no te enteras.

2. Tu servidor recibe pero falla al procesar. Error 500, log perdido, y el pago queda registrado en Stripe pero no en tu sistema.

3. Dos webhooks del mismo evento. Sin idempotencia, creas dos registros duplicados.

4. Race condition. Dos eventos relacionados llegan al mismo tiempo y tu logica falla.

Lo que debe tener tu integracion

Validacion de firma. Verificar que el webhook realmente viene de Stripe, no un atacante.

Idempotencia. Cada evento se procesa una sola vez. Si llega duplicado, detectarlo.

Retry logic. Si tu procesamiento falla, responder 500 para que Stripe reintente. No responder 200 si no procesaste.

Dead letter queue. Webhooks que fallan despues de varios reintentos deben ir a una cola para revisar manualmente.

Monitoreo. Dashboard que muestra webhooks recibidos, procesados, fallidos.

Alertas. Si hay webhooks fallando, alguien debe enterarse en minutos, no en dias.

El checklist antes de produccion

• Firma validada en cada request
• Idempotencia implementada con event ID
• Timeout configurado en tu handler
• Logs estructurados con event ID
• Dashboard de monitoreo activo
• Alertas configuradas para fallos

Un webhook que falla en silencio es un pago perdido. No descubras esto en el cierre de mes.