Webhooks y callbacks

Esta guía cubre los eventos que Matcher publica y los callbacks entrantes que los sistemas externos envían a Matcher.

Resumen

Eventos salientes: Matcher publica su catálogo de eventos de ciclo de vida en el backbone de streaming de la plataforma. Esos eventos te llegan como un stream, no como webhooks HTTP.
Callbacks entrantes: los sistemas externos, como una herramienta de tickets, avisan a Matcher cuando actúan sobre una excepción. Luego Matcher actualiza el estado de la excepción.

Eventos salientes

Matcher emite eventos cuando ocurren acciones significativas en el proceso de conciliación, y los publica en el backbone de streaming. Cada evento sigue su propio esquema en el stream de eventos.

Eventos disponibles

Las tablas de abajo listan el catálogo de eventos por dominio. Configuración

Evento	Disparador	Uso típico
`reconciliation_context.created`	Contexto de conciliación creado	Sincronización de aprovisionamiento
`reconciliation_context.updated`	Metadatos o estado del contexto modificados	Seguimiento de cambios de configuración
`reconciliation_source.created`	Fuente creada dentro de un contexto	Incorporación de fuentes
`match_rule.created`	Regla de coincidencia creada	Auditoría de cambios de reglas
`match_rule.reordered`	Prioridades de reglas reordenadas	Auditoría de cambios de reglas

Discovery

Evento	Disparador	Uso típico
`fetcher_connection.synced`	Conexión e instantánea de esquema sincronizadas	Monitoreo de Discovery
`fetcher_connection.unreachable`	Conexión marcada como inalcanzable	Alertas de conectividad
`extraction_request.created`	Solicitud de extracción creada	Monitoreo de extracciones
`extraction_request.submitted`	Extracción aceptada por el motor de extracción	Monitoreo de extracciones
`extraction_request.completed`	Extracción completada y entregada a la ingesta	Disponibilidad de datos
`extraction_request.failed`	Extracción fallida	Alertas de error

Ingesta

Evento	Disparador	Uso típico
`ingestion.completed`	Importación de archivo finalizada	Monitoreo del pipeline de datos
`ingestion.failed`	Importación de archivo fallida	Alertas de error
`transaction.ignored`	Transacción no conciliada marcada como ignorada	Registro de auditoría

Coincidencia

Evento	Disparador	Uso típico
`match_run.completed`	Trabajo de coincidencia finalizado	Monitoreo de trabajos, informes
`match_run.failed`	Trabajo de coincidencia fallido	Alertas de error
`match_group.confirmed`	Grupo de coincidencia confirmado	Actualizaciones downstream
`match_group.unmatched`	Coincidencia confirmada revertida	Seguimiento de correcciones
`transaction.matched`	Transacción marcada como conciliada	Registro de auditoría
`transaction.pending_review`	Un candidato no automático necesita revisión	Disparadores de la cola de revisión
`fee_variance.created`	Variación de comisión detectada	Investigación de comisiones

Excepciones y disputas

Evento	Disparador	Uso típico
`exception.assigned`	Excepción asignada a un responsable	Notificación al usuario
`exception.resolved`	Excepción resuelta	Sincronización de estado
`exception.dispatched`	Excepción enviada a un sistema de destino	Registro de auditoría
`exception.callback_processed`	Callback externo procesado	Sincronización de estado
`exception.force_match_resolved`	Excepción resuelta mediante coincidencia forzada	Workflows de aprobación
`exception.adjust_entry_resolved`	Excepción resuelta mediante asiento de ajuste	Registro de auditoría
`exception_comment.added`	Comentario agregado a una excepción	Sincronización de colaboración
`exception_comment.deleted`	Comentario de excepción eliminado	Sincronización de colaboración
`dispute.opened`	Disputa abierta para una excepción	Seguimiento de disputas
`dispute.won`	Disputa cerrada como ganada	Sincronización de estado
`dispute.lost`	Disputa cerrada como perdida	Sincronización de estado
`evidence.submitted`	Evidencia enviada a una disputa	Seguimiento de disputas

Gobernanza e informes

Evento	Disparador	Uso típico
`audit_log.created`	Entrada de registro de auditoría agregada	Monitoreo de cumplimiento
`archive_metadata.created`	Ciclo de vida de archivo iniciado	Monitoreo de archivado
`archive.uploaded`	Objeto de archivo subido	Monitoreo de archivado
`archive.completed`	Archivo verificado y completado	Monitoreo de archivado
`actor.pseudonymized`	Mapeo de actor seudonimizado	Monitoreo de cumplimiento
`export_job.created`	Trabajo de exportación encolado	Monitoreo de exportaciones
`export_job.succeeded`	Trabajo de exportación completado	Disponibilidad de descarga
`export_job.failed`	Trabajo de exportación fallido	Alertas de error
`export_job.expired`	Artefacto de exportación vencido	Ciclo de vida de la exportación

Callbacks entrantes

Los sistemas externos envían callbacks a Matcher para actualizar el estado de una excepción después de procesarla. El endpoint de callback acepta actualizaciones de estado, notas de resolución y cambios de responsable desde cualquier sistema externo.

Procesar un callback

El header X-Callback-Token autentica el endpoint de callback. Un JWT de operador no lo autentica. El header lleva un token opaco de la superficie de credenciales de callback. Cada campo de abajo es obligatorio. dueAt y updatedAt aceptan null, y payload puede ser un objeto vacío:

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/callback" \
 -H "X-Callback-Token: ***" \
 -H "X-Idempotency: callback-jira-1234" \
 -H "Content-Type: application/json" \
 -d '{
   "callbackType": "status_update",
   "externalSystem": "JIRA",
   "externalIssueId": "RECON-1234",
   "status": "RESOLVED",
   "resolutionNotes": "Verified: amount difference is expected bank wire fee",
   "assignee": "john.doe@company.com",
   "dueAt": null,
   "updatedAt": "2026-01-20T14:30:00Z",
   "payload": {}
 }'

El campo externalSystem identifica el sistema externo que procesó la excepción. Los valores comunes incluyen "JIRA", "SERVICENOW" o "WEBHOOK", pero los callbacks pueden informar cualquier identificador de sistema. Omitir cualquiera de los nueve campos obligatorios devuelve un 422.

Respuesta

{
  "status": "accepted"
}

Referencia de API: Procesar callback

Cuando Matcher procesa un callback, actualiza el estado de la excepción y registra la resolución en el registro de auditoría. El header X-Idempotency es obligatorio. Matcher lee la clave de idempotencia solo desde este header. Una solicitud que lleva una clave solo en X-Idempotency-Key o Idempotency-Key se rechaza con 400 (MTCH-0015), y no se procesa nada. Matcher deduplica un callback por su sistema externo, su excepción y su clave en conjunto. La misma clave en otra excepción o desde otro sistema externo es un callback nuevo.

Estado del callback

status mueve la excepción a ASSIGNED o RESOLVED. Matcher lee el valor sin distinguir mayúsculas de minúsculas.
Para mover la excepción a ASSIGNED, envía un assignee no vacío.
Cuando status es el estado actual de la excepción, Matcher mantiene el estado y actualiza assignee y dueAt si los envías.

Rechazos del callback

Estado	Código	Significado
`400`	`MTCH-0015`	La clave llegó solo en `X-Idempotency-Key` o `Idempotency-Key`.
`400`	`MTCH-0001`	El callback no es válido. Por ejemplo, el valor de `X-Idempotency` no tiene de 1 a 128 letras, dígitos, `:`, `_` o `-`, o un callback `ASSIGNED` no tiene `assignee`.
`409`	`MTCH-0504`	Otro callback con la misma clave todavía está en proceso. Envía la solicitud de nuevo más tarde.
`409`	`MTCH-0505`	Matcher no puede confirmar el estado de un callback anterior con la misma clave. Envía la solicitud de nuevo más tarde.
`429`	`MTCH-0506`	El sistema externo envió más callbacks de los que permite su límite de tasa. Envía la solicitud de nuevo más tarde.

Un token de callback desconocido o revocado recibe 404. Cuando Matcher no puede verificar el token, responde 503.

Reintento automático para callbacks fallidos

Si un callback anterior con la misma clave de idempotencia falló durante el procesamiento, Matcher intenta de forma automática readquirir el lock de idempotencia y reprocesar el callback. No necesitas generar una nueva clave de idempotencia cuando reintentas un callback fallido. Reenvía la misma solicitud y Matcher se encarga de la recuperación. El comportamiento de reintento se aplica solo a los callbacks con un estado interno failed. Matcher sigue deduplicando los callbacks que se completaron con éxito.

Credenciales de callback

Un Bearer token opaco autentica los callbacks entrantes. El sistema externo envía este token en el header X-Callback-Token. Emites, listas, rotas y revocas estas credenciales de callback a través de una superficie CRUD dedicada bajo /v1/exceptions/callbacks/credentials. Cada credencial pertenece al tenant de quien llama. Matcher almacena solo el hash SHA-256 del token del lado del servidor. Las respuestas de emisión y de rotación devuelven el token en bruto exactamente una vez.

Acción	Método y ruta	Notas
Emitir credencial	`POST /v1/exceptions/callbacks/credentials`	Crea una credencial y devuelve el token en bruto una vez (`201`).
Listar credenciales	`GET /v1/exceptions/callbacks/credentials`	Lista los metadatos de las credenciales del tenant (nunca los tokens en bruto).
Rotar credencial	`POST /v1/exceptions/callbacks/credentials/{credentialId}/rotate`	Sustituye de forma atómica una credencial activa por una recién emitida (la misma etiqueta) y devuelve el nuevo token en bruto una vez; la anterior se revoca en la misma transacción.
Revocar credencial	`DELETE /v1/exceptions/callbacks/credentials/{credentialId}`	Revoca una credencial de forma terminal (`204`); auditado solo por adición.

Referencia de API:

Emitir una credencial

La solicitud necesita un cuerpo JSON. Envía {} si no defines una etiqueta. El campo externalSystem es opcional. Proporciónalo como una etiqueta legible por el operador para el sistema que este token autentica.

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/callbacks/credentials" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "externalSystem": "stripe" }'

La respuesta 201 (CredentialSecretResponse) devuelve:

Campo	Descripción
`token`	Bearer token en bruto, expuesto una vez. Configúralo como valor del header `X-Callback-Token` en el sistema externo.
`credentialId`	Id sustituto de la credencial emitida (se usa para rotar/revocar).
`createdAt`	Hora de emisión (RFC 3339, UTC).
`externalSystem`	La etiqueta devuelta para confirmación.
`webhookUrlHint`	Forma informativa de la URL de callback entrante para configurar por fuera; el placeholder `{exceptionId}` se completa en cada callback.

Solo las respuestas de emisión y de rotación muestran el token en bruto. Guárdalo de forma segura al recibirlo. No puedes recuperarlo otra vez. Si pierdes o filtras el token, rota o revoca la credencial.

Rotar una credencial

cURL

curl -X POST "https://api.matcher.example.com/v1/exceptions/callbacks/credentials/{credentialId}/rotate" \
 -H "Authorization: Bearer $TOKEN"

La rotación devuelve un nuevo CredentialSecretResponse (201, un nuevo token en bruto) y revoca la credencial anterior en la misma transacción. Los callbacks que todavía envían el token anterior fallan, así que actualiza el sistema externo con el nuevo token de inmediato.

Revocar una credencial

cURL

curl -X DELETE "https://api.matcher.example.com/v1/exceptions/callbacks/credentials/{credentialId}" \
 -H "Authorization: Bearer $TOKEN"

La revocación es terminal: la credencial ya no puede autenticar callbacks entrantes.

Próximos pasos

Enrutamiento de excepciones

Configura reglas que enrutan excepciones.

Fuentes externas

Configura fuentes de datos. Entre ellas, solo las conexiones con agregadores reciben webhooks.

Resumen

Guías

Console

Operaciones

Webhooks y callbacks

Resumen

Eventos salientes

Eventos disponibles

Callbacks entrantes

Procesar un callback

Respuesta

Estado del callback

Rechazos del callback

Reintento automático para callbacks fallidos

Credenciales de callback

Emitir una credencial

Rotar una credencial

Revocar una credencial

Próximos pasos

Enrutamiento de excepciones

Fuentes externas

​Resumen

​Eventos salientes

​Eventos disponibles

​Callbacks entrantes

​Procesar un callback

​Respuesta

​Estado del callback

​Rechazos del callback

​Reintento automático para callbacks fallidos

​Credenciales de callback

​Emitir una credencial

​Rotar una credencial

​Revocar una credencial

​Próximos pasos

Enrutamiento de excepciones

Fuentes externas

Resumen

Eventos salientes

Eventos disponibles

Callbacks entrantes

Procesar un callback

Respuesta

Estado del callback

Rechazos del callback

Reintento automático para callbacks fallidos

Credenciales de callback

Emitir una credencial

Rotar una credencial

Revocar una credencial

Próximos pasos