Los webhooks de pago entrantes reconocen la recepción por separado de la mutación del libro mayor, deduplican por identidad del evento del proveedor, reconcilian resultados desconocidos mediante la consulta al proveedor y tratan el libro mayor interno como autoritativo cuando surgen conflictos de orden o contenido.
Estado del paquete: Paquete de referencia asistido por IA. La validación estática del paquete ha pasado; los escenarios de implementación aún no se han ejecutado y se requiere revisión humana del dominio antes de su adopción estable.
Decisión
Los webhooks del proveedor de pago llegan a un endpoint de ingreso autenticado que verifica la firma antes de la persistencia. Las firmas inválidas devuelven 401 sin almacenar un recibo. Los payloads válidos se persisten como registros de recibo; se devuelve HTTP 200 después del almacenamiento duradero, antes de la mutación del libro mayor. Una caché rápida de deduplicación puede expirar después de dedupe_store_ttl_days, pero un registro de eventos duradero e inmutable mantiene la identidad del evento del proveedor al menos durante el período de retención del libro mayor y auditoría. manual_review se resuelve en aplicado o rechazado mediante operator_resolution. Los resultados desconocidos permanecen en reconciliación hasta que la consulta al proveedor tenga éxito o el tiempo de espera los mueva a manual_review.
Alcance
- Reconocimiento de recibo de webhook, verificación de firma, almacenamiento de deduplicación, trabajador de reconciliación, cliente de consulta al proveedor y idempotencia de mutación del libro mayor.
- Rutas de resolución de revisión manual y comportamiento posterior al TTL de deduplicación.
Fuera de este bloque
- Entrega de webhooks salientes a clientes.
- Actualizaciones de proyección de derechos (ver bloque de derechos).
- UI de recopilación de datos de tarjeta PCI y almacenamiento de credenciales.
Contrato
- Se envía HTTP 200 indicando éxito de recibo solo después de que la verificación de firma pase y el payload bruto se almacene de forma duradera con la ID del evento del proveedor.
- Firma inválida devuelve 401; invalid_signature_stores_receipt es falso; no se crea fila de recibo ni se programa mutación del libro mayor.
- Evento duplicado del proveedor dentro de dedupe_store_ttl_days reconoce éxito sin reaplicar mutación del libro mayor.
- Después de que la caché rápida de deduplicación expira, la ID del evento del proveedor se verifica contra el registro duradero de eventos; un evento previamente aplicado reconoce éxito sin otra mutación del libro mayor.
- Un evento genuinamente no visto puede entrar en reconciliación solo después de que su ID de evento del proveedor se inserte atómicamente en el registro duradero o gane una restricción de unicidad equivalente.
- La mutación del libro mayor nunca ocurre en el hilo del manejador HTTP; se ejecuta en un trabajador que transiciona el estado de reconciliación independientemente del reconocimiento.
- manual_review transiciona a aplicado o rechazado solo con registros de auditoría operator_resolution adecuados para exportación financiera.
- Conflictos entre consulta al proveedor y payload de webhook sobre monto bloquean el crédito automático y entran en manual_review.
- Eventos que llegan tarde con marcas de tiempo efectivas más antiguas no revierten filas del libro mayor liquidadas sin un tipo de evento de reversión explícito.
Guía de implementación
- Almacenar los bytes brutos del webhook antes del análisis JSON para que la verificación de firma pueda reproducirse.
- Usar las transiciones de reconciliation-states.yaml en los paneles de operador con métricas separadas para reconocimiento versus éxito en libro mayor.
- Programar reintentos con retroceso exponencial para errores de API del proveedor; no otorgar acceso provisional a menos que allow_provisional_access sea explícitamente verdadero en el perfil.
- Separar métricas de reconocimiento de métricas de mutación del libro mayor para detectar trabajadores atascados después del recibo.
Manejo de fallos y salvaguardas
- El fallo del trabajador después del reconocimiento se reanuda desde el recibo almacenado sin doble reconocimiento al proveedor.
- El tiempo de espera de consulta que excede el límite del perfil mueve a manual_review en lugar de asumir pago.
- Las claves de idempotencia en escrituras del libro mayor previenen cargos duplicados cuando los trabajadores reintentan.
Verificación y operaciones
- Las pruebas cubren rechazo por firma inválida, expiración de caché con deduplicación duradera, resolución manual_review a aplicado y rechazado, y reembolsos fuera de orden.
- Las métricas rastrean el retraso entre reconocimiento y mutación, profundidad de cola de reconciliación, tasa de revisión manual y conteo terminal de rechazados.
- Los simulacros de reconciliación simulan caída del proveedor durante volumen pico de webhooks.
Suposiciones de adopción
- Los nombres y valores numéricos en example.yaml y reconciliation-states.yaml son un perfil de adopción, no valores predeterminados universales.
- El equipo adoptante selecciona proveedores de pago y define reglas de conflicto de autoridad del libro mayor con las partes interesadas financieras.