Los webhooks permiten la comunicación en tiempo real entre Matcher y sistemas externos. Esta guía cubre las notificaciones de eventos salientes y los callbacks de resolución entrantes.
Descripción general Matcher permite comunicación bidireccional mediante webhooks:
Webhooks salientes : Matcher notifica a sistemas externos cuando ocurren eventosCallbacks entrantes : Sistemas externos notifican a Matcher cuando se toman acciones
Cuando algo sucede en Matcher, como una nueva excepción o una coincidencia completada, envía un evento a sus endpoints configurados. Los sistemas externos como JIRA o ServiceNow pueden entonces enviar callbacks para actualizar el estado de excepciones o cerrar elementos automáticamente. Este flujo bidireccional mantiene sus herramientas sincronizadas sin intervención manual.
Eventos salientes Matcher emite eventos cuando ocurren acciones significativas en el proceso de conciliación.
Eventos disponibles Evento Disparador Uso típico ingestion.completedImportación de archivo finalizada Monitoreo de pipeline de datos ingestion.failedImportación de archivo falló Alertas de error match.createdNueva coincidencia propuesta Registro de auditoría match.confirmedCoincidencia aprobada Actualizaciones downstream match.rejectedCoincidencia rechazada Disparadores de investigación match.force_matchedCoincidencia forzada manual aplicada Pista de auditoría, flujos de aprobación match.unmatchedCoincidencia revertida manualmente Pista de auditoría, seguimiento de correcciones match_run.startedTrabajo de coincidencia automático iniciado Monitoreo de trabajos match_run.completedTrabajo de coincidencia automático finalizado Monitoreo de trabajos, reportes match_run.failedTrabajo de coincidencia automático falló Alertas de error exception.createdNueva excepción Creación de tickets exception.assignedExcepción asignada Notificación al usuario exception.escalatedExcepción escalada Alertas de gerencia exception.resolvedExcepción resuelta Sincronización de estado exception.sla_warningSLA aproximándose Alertas proactivas exception.sla_breachSLA excedido Disparadores de escalamiento context.closedPeríodo de conciliación cerrado Disparadores de reportes
Estructura del payload de eventos Todos los eventos siguen una estructura consistente:
{ "id" : "evt_001" , "type" : "exception.created" , "timestamp" : "2024-01-20T10:30:00Z" , "version" : "1.0" , "tenant_id" : "tenant_001" , "context_id" : "ctx_abc123" , "data" : { // Datos específicos del evento }, "metadata" : { "correlation_id" : "req_xyz789" , "source" : "matching_engine" } }
Payloads de eventos Ingestion completed Se dispara cuando un lote de transacciones se importa exitosamente.
{ "id" : "evt_ing_001" , "type" : "ingestion.completed" , "timestamp" : "2024-01-20T10:30:00Z" , "data" : { "job_id" : "job_imp_001" , "source_id" : "src_bank456" , "source_name" : "Chase Bank" , "file_name" : "statement_january.csv" , "summary" : { "total_rows" : 1250 , "imported" : 1240 , "duplicates_skipped" : 8 , "validation_errors" : 2 }, "duration_seconds" : 45 , "started_at" : "2024-01-20T10:29:15Z" , "completed_at" : "2024-01-20T10:30:00Z" } }
Match confirmed Se dispara cuando una coincidencia es aprobada (automática o manual).
{ "id" : "evt_mtch_001" , "type" : "match.confirmed" , "timestamp" : "2024-01-20T10:30:01Z" , "data" : { "match_id" : "match_001" , "confidence" : 100 , "rule_id" : "rule_exact001" , "rule_name" : "Exact Match" , "confirmation_type" : "AUTO" , "transactions" : [ { "id" : "txn_bank_001" , "source_name" : "Chase Bank" , "amount" : 1000.0 , "currency" : "USD" , "date" : "2024-01-15" }, { "id" : "txn_ledger_001" , "source_name" : "Main Ledger" , "amount" : 1000.0 , "currency" : "USD" , "date" : "2024-01-15" } ], "variance" : { "amount_diff" : 0 , "date_diff_days" : 0 } } }
Exception created Se dispara cuando se identifica una nueva excepción.
{ "id" : "evt_exc_001" , "type" : "exception.created" , "timestamp" : "2024-01-20T10:30:00Z" , "data" : { "exception_id" : "exc_001" , "severity" : "HIGH" , "reason" : "NO_MATCH_FOUND" , "reason_details" : "No se encontró transacción coincidente dentro de la tolerancia" , "transaction" : { "id" : "txn_bank_999" , "source_id" : "src_bank456" , "source_name" : "Chase Bank" , "external_id" : "BANK-2024-999" , "amount" : 15000.0 , "currency" : "USD" , "date" : "2024-01-15" , "reference" : "Transferencia bancaria #7890" }, "candidates" : [ { "transaction_id" : "txn_ledger_777" , "confidence" : 55 , "rejection_reason" : "Por debajo del umbral del 60%" } ], "sla" : { "due_at" : "2024-01-21T10:30:00Z" , "hours_remaining" : 24 } } }
Exception resolved Se dispara cuando una excepción es resuelta.
{ "id" : "evt_exc_002" , "type" : "exception.resolved" , "timestamp" : "2024-01-20T14:30:00Z" , "data" : { "exception_id" : "exc_001" , "resolution" : { "type" : "FORCE_MATCH" , "match_id" : "match_forced_001" , "resolved_by" : "user_123" , "notes" : "Verificado: la diferencia de monto es la comisión bancaria por transferencia" }, "time_to_resolution" : { "hours" : 4 , "within_sla" : true } } }
Match force matched Se dispara cuando un usuario fuerza manualmente una coincidencia entre transacciones.
{ "id" : "evt_force_001" , "type" : "match.force_matched" , "timestamp" : "2024-01-20T14:30:00Z" , "data" : { "match_id" : "match_forced_001" , "exception_id" : "exc_001" , "forced_by" : "user_123" , "reason" : "La diferencia de monto es una comisión bancaria documentada" , "notes" : "Verificado con extracto bancario mostrando comisión de $250 por transferencia deducida" , "transactions" : [ { "id" : "txn_bank_999" , "source_name" : "Chase Bank" , "amount" : 15000.0 , "currency" : "USD" , "date" : "2024-01-15" }, { "id" : "txn_ledger_777" , "source_name" : "Main Ledger" , "amount" : 15250.0 , "currency" : "USD" , "date" : "2024-01-14" } ], "variance" : { "amount_diff" : 250.0 , "amount_variance_percent" : 1.67 , "date_diff_days" : 1 }, "requires_approval" : true , "approval_threshold" : 10000.0 } }
Los eventos de coincidencia forzada se usan comúnmente para activar flujos de aprobación cuando la variación excede los umbrales de la empresa.
Match unmatched Se dispara cuando una coincidencia previamente confirmada es revertida.
{ "id" : "evt_unmatch_001" , "type" : "match.unmatched" , "timestamp" : "2024-01-20T15:45:00Z" , "data" : { "match_id" : "match_001" , "unmatched_by" : "user_456" , "reason" : "Coincidencia incorrecta - las transacciones pertenecen a facturas diferentes" , "notes" : "Txn bancaria es para Factura #1234, txn del libro mayor es para Factura #5678" , "original_match" : { "confirmed_at" : "2024-01-15T10:00:00Z" , "confirmed_by" : "system" , "confidence" : 85 , "rule_name" : "Tolerance Match" }, "transactions" : [ { "id" : "txn_bank_001" , "source_name" : "Chase Bank" , "amount" : 1000.0 , "currency" : "USD" }, { "id" : "txn_ledger_001" , "source_name" : "Main Ledger" , "amount" : 1005.0 , "currency" : "USD" } ], "action" : { "exceptions_created" : [ "exc_new_001" , "exc_new_002" ], "status" : "Ambas transacciones devueltas al pool de no coincidentes" } } }
Deshacer una coincidencia confirmada crea nuevas excepciones para ambas transacciones y genera una entrada completa en el registro de auditoría.
Match run completed Se dispara cuando una ejecución de coincidencias automática o manual finaliza.
{ "id" : "evt_run_001" , "type" : "match_run.completed" , "timestamp" : "2024-01-20T06:05:23Z" , "data" : { "run_id" : "run_001" , "context_id" : "ctx_abc123" , "context_name" : "Daily Bank Reconciliation" , "trigger" : "SCHEDULED" , "started_at" : "2024-01-20T06:00:00Z" , "completed_at" : "2024-01-20T06:05:23Z" , "duration_seconds" : 323 , "statistics" : { "transactions_processed" : 1250 , "matches_found" : 1180 , "matches_confirmed" : 1120 , "matches_pending_review" : 60 , "exceptions_created" : 70 , "by_confidence" : { "high_90_100" : 1120 , "medium_60_89" : 60 , "low_0_59" : 0 } }, "performance" : { "transactions_per_second" : 3.87 , "avg_rule_evaluation_ms" : 12.5 } } }
SLA warning / SLA breach Se dispara cuando se alcanzan los umbrales de SLA.
{ "id" : "evt_sla_001" , "type" : "exception.sla_warning" , "timestamp" : "2024-01-20T18:30:00Z" , "data" : { "exception_id" : "exc_001" , "severity" : "HIGH" , "sla" : { "due_at" : "2024-01-21T10:30:00Z" , "hours_remaining" : 16 , "percent_remaining" : 25 }, "assigned_to" : "user_123" , "escalation_path" : [ "user_manager" , "user_director" ] } }
Seguridad de webhooks Verificación de firma Todas las entregas de webhooks incluyen un encabezado de firma para verificación:
X-Matcher-Signature: sha256=abc123... X-Matcher-Timestamp: 1705758600
Proceso de verificación:
Concatenar timestamp y body: {timestamp}.{body}
Calcular HMAC-SHA256 usando el secreto del webhook
Comparar con el encabezado de firma
Ejemplo (Node.js): const crypto = require ( 'crypto' ); function verifyWebhook ( payload , signature , timestamp , secret ) { const signedPayload = ` ${ timestamp } . ${ payload } ` ; const expectedSignature = crypto . createHmac ( 'sha256' , secret ) . update ( signedPayload ) . digest ( 'hex' ); return `sha256= ${ expectedSignature } ` === signature ; }
Ejemplo (Python): import hmac import hashlib def verify_webhook ( payload , signature , timestamp , secret ): signed_payload = f " { timestamp } . { payload } " expected = hmac.new( secret.encode(), signed_payload.encode(), hashlib.sha256 ).hexdigest() return f "sha256= { expected } " == signature
Lista de IPs permitidas Matcher envía webhooks desde rangos de IP específicos:
Configure su firewall para permitir estos rangos.
Requisitos de TLS
Mínimo TLS 1.2
Se requiere certificado SSL válido
Certificados autofirmados no soportados en producción
Lógica de reintentos Las entregas de webhooks fallidas se reintentan con retroceso exponencial.
Política de reintentos por defecto Intento Retraso Espera total 1 Inmediato 0s 2 5 segundos 5s 3 30 segundos 35s 4 2 minutos 2m 35s 5 10 minutos 12m 35s 6 1 hora 1h 12m 35s
Configuración de reintentos personalizada { "retry" : { "max_attempts" : 5 , "initial_delay_seconds" : 10 , "max_delay_seconds" : 3600 , "backoff_multiplier" : 2 } }
Condiciones de reintento Los reintentos ocurren para:
Respuestas HTTP 5xx
Timeouts de conexión
Fallos de resolución DNS
Sin reintento para:
Respuestas HTTP 4xx (excepto 429)
Certificados SSL inválidos
Webhook deshabilitado
Mejores prácticas
Verifique las firmas de webhooks
Siempre verifique la firma HMAC antes de procesar los payloads de webhooks. Esto previene solicitudes falsificadas.
Retorne una respuesta 2xx dentro de 5 segundos. Procese el evento de forma asíncrona si es necesario.
Maneje duplicados de forma idempotente
Los eventos pueden entregarse más de una vez. Use el ID del evento para deduplicar.
Monitoree la salud de las entregas
Configure alertas para tasas de falla de webhooks. Investigue las fallas persistentes de inmediato.
Suscríbase solo a los eventos que necesita. El filtrado reduce el ruido y la carga de procesamiento.
Pruebe antes de producción
Use el endpoint de prueba para verificar que su manejador de webhooks funciona correctamente antes de habilitar en producción.
Próximos pasos 
