Recursos · 54
Webhooks: manejan repeticiones, retrasos y recuperación
Convierte una notificación recibida en un efecto empresarial único, trazable y recuperable tras un fallo.
Actualizado · 3 min
Lo que esta guía ayuda a lograr
- Autenticar notificaciones
- Separar recibo del procesamiento
- Evitar efectos duplicados
- Recuperar eventos bloqueados
Comprobación rápida
- ¿Qué bytes están firmados?
- ¿Cuándo es perdurable el recibo?
- ¿Pueden dos trabajadores actuar juntos?
- ¿El proveedor garantiza el pedido?
- ¿Cómo se encuentra un evento perdido?
Método paso a paso
- 1
Leer el contrato del proveedor
Tipos de registro, versión, contexto de cuenta, firmas, tiempos y reglas de reintento. Stripe afirma que los pedidos de entrega no están garantizados y pueden producirse duplicados; no aplique un retraso específico de Stripe a cada API.
Entregable: contrato de proveedor fechado.
- 2
Validar antes de efectos
Verificar firmas con la biblioteca y raw body requeridas por el proveedor. Limite los tamaños y tipos aceptados. Pruebe firmas no válidas y contextos de cuentas inesperados en un entorno autorizado sin registrar secretos.
Entregable: denegaciones sin efectos.
- 3
Persistir antes de reconocer
Separar recibo duradero de procesamiento lento. Si la cola no puede aceptar el evento, no lo informe como retenido. El éxito indica la recepción de su contrato, no necesariamente la finalización de la acción comercial.
Entregable: estados recibido, procesando, completado y bloqueado.
- 4
Aplicar idempotencia
Definir claves de eventos e identidad de efecto empresarial. Pruebe repeticiones simultáneas en lugar de solo entregas secuenciales. Una verificación preliminar sin restricciones atómicas ni bloqueos puede permitir que dos trabajadores creen el mismo efecto.
Entregable: evidencia de unicidad del efecto.
- 5
Manejar retrasos y desorden
No asuma que una notificación antigua describe el estado actual. Consultar la fuente cuando el contrato lo permita y aplicar transiciones comerciales validadas. Retener eventos que aún no se pueden interpretar.
Entregable: transiciones y pruebas de orden inverso.
- 6
Conciliar y reproducir
Preparar una cola de errores con propietario, causa, intentos y cierre. Mantenga la protección duplicada durante la reproducción. Compare periódicamente el proveedor y la aplicación: la recuperación exitosa no prueba que no se haya perdido ningún evento.
Entregable: procedimiento de recuperación y reporte de discrepancias.
Hoja de cálculo reutilizable
Complete con sus observaciones autorizadas. Estos campos son una plantilla de trabajo, no resultados observados.
| Campo | Información a registrar |
|---|---|
| Evento | Proveedor, cuenta, identificador y versión |
| Recibo | Firma validada y marca de tiempo duradera |
| Efecto | Evidencias de clave, estado y unicidad de negocio |
| Recuperación | Causa, intento, titular y cierre |
Ejemplo trabajado ficticio
Situación ilustrativa
Ejemplo ficticio: dos trabajadores reciben la misma notificación de confirmación durante la recuperación.
Decisión y pruebas esperadas
Una restricción de efecto comercial y un estado transaccional únicos permiten un cumplimiento mientras ambas entregas permanecen rastreables.
Distinguir los mecanismos
| Mecanismo | Propósito | Verificación o limitación |
|---|---|---|
| Firma | Validar origen según el contrato | No hace que los efectos sean únicos |
| Deduplicación | Reconocer notificaciones repetidas | Verificar también simultaneidad y efectos de negocio |
| Conciliación | Encuentra omisiones y diferencias | Nombra la fuente y el periodo |
Indicadores de gestión
| Indicador | Qué mide | Primera acción |
|---|---|---|
| Edad de la cola | Retraso de eventos no finalizados | Inspeccionar los más antiguos |
| Efectos duplicados | Acciones comerciales repetidas por error | Atomicidad correcta |
| Lagunas en fuente/aplicación | Estados ausentes o divergentes | Conciliar con evidencia de cierre |
Errores comunes
- Análisis previo a la verificación del cuerpo firmado
- Acuse de recibo antes del recibo duradero
- Asumiendo entrega ordenada
- Probando duplicados solo de forma secuencial
Preguntas frecuentes
¿El éxito de HTTP significa que el procesamiento está completo?
Depende del contrato. Con el procesamiento asincrónico, debería significar un recibo duradero mientras que el estado del negocio se rastrea por separado.
¿Se puede asumir la entrega exactamente una vez?
Diseño para repeticiones y fallos bajo el contrato real, con efectos únicos y conciliación.
¿Se debe conservar todo el cuerpo?
Sólo cuando sea necesario con acceso y retención adecuados. Los rastros mínimos deberían respaldar el diagnóstico y la recuperación sin guardar secretos.
Referencias oficiales
Las referencias respaldan el método. Adapte los controles a su contexto; no constituyen certificación. Los títulos de referencia originales y los documentos fuente pueden estar en otro idioma.
Referencias consultadas el .
