webhook-inbox
En desarrolloUn receptor de webhooks de Stripe que aguanta eventos repetidos, desordenados y que fallan
Rol: Desarrollador en solitario
En solitario · Desde nov 2026 · Repo público
Un servicio en NestJS que verifica la firma de Stripe, guarda cada evento antes de procesarlo, lo aplica en orden, reintenta los fallos con espera creciente y deja los que no se pueden procesar en una cola que se puede revisar y reenviar.
Problema
Un endpoint de webhooks que funciona en un tutorial falla en silencio en producción: Stripe reintenta, así que el mismo evento llega dos veces; no garantiza el orden, así que un reembolso puede llegar antes del pago que reembolsa; y un endpoint lento hace que Stripe lo mande todo otra vez.
Solución
El endpoint solo comprueba la firma sobre el cuerpo crudo, inserta el evento con su id de Stripe como clave y responde 200. Un worker toma los eventos listos con UPDATE ... FOR UPDATE SKIP LOCKED y aplica cada uno en la misma transacción que lo marca como hecho. Cada pedido recuerda la fecha del último evento que aplicó, así que uno más viejo se descarta.
Todavía no
Nunca se conectó a una cuenta real de Stripe: las firmas de las pruebas y del simulador salen del helper del SDK con un secreto de prueba. Maneja tres tipos de evento, la tabla de pedidos es un pretexto, no medí el rendimiento y no hay métricas ni trazas.
Puntos clave de arquitectura
- 20 entregas simultáneas del mismo evento dejan una fila y una sola respuesta que lo marca como nuevo. Quitar ON CONFLICT rompe las dos pruebas de duplicados
- Un reembolso procesado antes que su pago termina igual como reembolsado, y los eventos del mismo segundo se resuelven por estado para que el resultado no dependa del orden de llegada. Quitar la guarda de orden rompe tres pruebas
- Los reintentos esperan 5 s por 2 elevado al intento, con tope de una hora y jitter completo, y a los 6 intentos el evento pasa a una cola de muertos detrás de un endpoint con token que puede reenviarlo
- Quité SKIP LOCKED para comprobar mis pruebas y la de tres workers siguió pasando: la unicidad la da el UPDATE al reevaluar su WHERE, y SKIP LOCKED solo evita esperar. Corregí mi propio comentario y agregué una prueba con una fila retenida por otra transacción, que sí falla sin él
- 31 pruebas corren contra un contenedor real de PostgreSQL, porque ON CONFLICT, SKIP LOCKED y las transacciones son comportamiento de la base que un mock no muestra