Arquitectura de Integración Técnica
Investigación
Práctica
Configuración de la ruta /api/webhooks en Next.js, propuesta técnica y un microservicio convertido en API.
Entregables
- Ruta /api/webhooks/stripe: firma HMAC-SHA256, tolerancia de 5 min e idempotencia por event_id
- Respaldo del checkout: el webhook registra el pedido aunque el comprador cierre la pestaña
- Microservicio de webhooks en Rust con Swagger (bandeja idempotente, reintentos y dead letter)
- Propuesta técnica
- Investigación, bibliografía APA y conclusiones
Dónde vive en el producto
Recorrido de un webhook
Stripe avisa de cada cobro, rechazo, reembolso y transferencia. Cada paso aplica una defensa; debajo, lo que pasa si falla.
Stripe
Firma el cuerpo con HMAC-SHA256 y el secreto whsec_
Stripe-Signature: t=…,v1=…
Reintenta hasta 3 días si no recibe 2xx
Next.js
Verifica firma y antigüedad (≤ 5 min) sobre el cuerpo crudo
POST /api/webhooks/stripe
400 · firma inválida o vieja
Bandeja (Rust)
Registra el event_id y decide: procesar u omitir
POST /v1/events
200 SKIP · duplicado
Manejador
Relee el objeto en Stripe y actualiza checkout
POST /v1/events/{id}/result
500 · FAILED → Stripe reintenta
Probar la ruta /api/webhooks/stripe
Toma el evento más reciente de la cuenta de prueba de Stripe, lo firma con el secreto del endpoint y lo entrega como lo haría Stripe.
Bandeja de webhooks (microservicio Rust)
GET /api/webhooks → servicio webhooks: /v1/stats, /v1/events y /v1/rejections.
—
Entregas
—
Procesados
—
Ignorados
—
Duplicados omitidos
—
Fallidos
—
Dead letter
—
Rechazados
| Hora | Evento | Estado | Intentos | Entregas | Resultado |
|---|
Tokens transaccionales
| Token | Quién lo usa | Qué protege |
|---|---|---|
PaymentMethod pm_1SXq… | Stripe.js en el navegador | El número de tarjeta nunca toca DopamInk (PCI SAQ A) |
client_secret pi_3SXq…_secret_… | Next.js → navegador | Solo ese navegador confirma ese PaymentIntent |
Idempotency-Key pi-{quote}-once · release-{pedido}-{hito} | Next.js → Stripe | Un reintento de red no cobra ni transfiere dos veces |
Stripe-Signature t=1792300000,v1=5f2b… | Stripe → /api/webhooks | El evento viene de Stripe y no se alteró ni se repitió |
event_id evt_3SXq… | Bandeja de webhooks | Cada evento produce su efecto una sola vez |
Cookie de sesión dopamink_session (HMAC-SHA256) | Next.js | Solo el comprador ve y libera sus pedidos |
Manejo de excepciones
| Excepción | Respuesta | Después |
|---|---|---|
| Firma ausente, inválida o vieja | 400 + registro en /v1/rejections | No se procesa; queda en la bitácora de rechazos |
| Evento ya procesado | 200 SKIP (DUPLICATE) | Stripe deja de reenviarlo; no hay segundo efecto |
| Otra entrega lo procesa ahora | 409 EVENT_IN_PROGRESS | Stripe lo reintenta; el lease de 30 s evita bloqueos |
| Bandeja o checkout caídos | 503 / 500 + evento FAILED | Stripe reintenta con espera exponencial |
| Quinto fallo del mismo evento | 200 + DEAD_LETTER | Se deja de reintentar y espera revisión manual |
| Pago de una reserva vencida | 200 PROCESSED | Se reembolsa el cargo (refund con Idempotency-Key) |