Separar recepción y procesamiento terminado
Las garantías dependen del proveedor. Stripe documenta posibles duplicados y ausencia de orden garantizado. Una respuesta HTTP de éxito debe corresponder a recepción duradera o al procesamiento previsto, no solo a la llegada a memoria.
| Situación | Comportamiento esperado | Evidencia útil |
|---|---|---|
| Mismo evento recibido dos veces | Evitar repetir el efecto de negocio. | ID procesado y resultado persistente. |
| Evento antiguo llega después | No sobrescribir ciegamente un estado reciente. | Estado oficial y regla de transición. |
| Procesamiento pesado | Recepción duradera y trabajo diferido. | Estado de cola y resultado del trabajador. |
| Entrega ausente | Conciliar y recuperar según el proveedor. | Diferencia identificada y corrección comprobada. |
Construir una recepción verificable
- Compruebe HTTPS, firma y protección contra repetición según el protocolo. Stripe verifica la firma sobre el cuerpo original; transformar JSON antes puede invalidarla.
- Registre de forma duradera el evento o su procesamiento antes del acuse apropiado. Distinga ID de entrega, ID de evento y clave de idempotencia de la acción.
- Pruebe duplicados, desorden, interrupción y reinicio del trabajador. Consulte el estado oficial del objeto si un evento antiguo no permite decidir con seguridad.
Organizar recuperación y conciliación
Documente intentos, plazos, eventos pendientes y conciliación con el proveedor. Un acuse rápido puede ocultar un fallo posterior. Supervise también la acción final y limite secretos y datos personales en registros.
Fuentes primarias
Gestionar los webhooks repetidos de forma segura.
Una notificación puede repetirse tras un tiempo de espera o una respuesta perdida. La fiabilidad depende de la verificación del origen, un identificador de evento y un procesamiento que distinga un mensaje nuevo de uno duplicado.
- Verificar cada solicitud mediante el mecanismo del proveedor.
- Probar los reintentos, los duplicados y el orden de llegada modificado.
- Confirmar de forma consistente tras el procesamiento o la puesta en cola persistente.
Fuente primaria: IETF RFC 9457 — Problem Details for HTTP APIs. Método relacionado: consultar la guía práctica.