Matcher events

Matcher emits domain events as CloudEvents 1.0 messages in binary content mode over Kafka, published through lib-streaming. Every event travels in the shared envelope: ce-type names the event as studio.lerian.<resource>.<event>, ce-subject carries the aggregate id, ce-tenantid the owning tenant, and ce-schemaversion the payload version — 1.0.0 for every event below. ce-source comes from STREAMING_CLOUDEVENTS_SOURCE and is required when streaming is enabled; deployments conventionally set matcher, so topics land on matcher.<resource>.<event> (see Topic naming). Money amounts — fee values, adjustment amounts — cross the wire as decimal strings, never floats. Matcher serves its full event catalog at GET /system/matcher/streaming/manifest. This page covers the Kafka streaming plane. Matcher’s exception webhook dispatch — HTTP callbacks for exception routing — is a separate surface, documented in Webhooks and callbacks.

Delivery policies

Matcher’s catalog uses two delivery policies:

Outbox-backed events are written to the outbox in the same database transaction as the state change; a relay publishes committed rows and retries through broker outages. These are the audit-grade facts (matching outcomes, exception resolutions, disputes, governance). This policy cannot be weakened per deployment.
Direct events publish after the transaction commits, best-effort, falling back to the outbox only when the broker circuit is open. These are configuration and operational lifecycle signals.

Each table below states the policy for its events.

Matching events

Outbox-backed: transaction.matched, transaction.pending_review. Direct: the rest.

Event (`ce-type`)	Topic	Fires when	Key payload
`studio.lerian.transaction.matched`	`matcher.transaction.matched`	A transaction line reaches terminal MATCHED in a match-run commit — one event per matched line.	`transaction_id`, `context_id`, `match_run_id`, `previous_status`, `status`, `match_group_id`?, `candidate_match_group_id`?, `source_id`?, `matched_at`?
`studio.lerian.transaction.pending_review`	`matcher.transaction.pending_review`	A candidate match needs human review (non-automatic rule).	Same schema, with `pending_review_at`?
`studio.lerian.transaction.ignored`	`matcher.transaction.ignored`	A transaction is excluded from matching.	`transaction_id`, `ingestion_job_id`, `context_id`, `source_id`, `previous_status`, `status`, `extraction_status`, `updated_at`
`studio.lerian.match_run.completed`	`matcher.match_run.completed`	A match run finishes. Lender consumes this event to translate reconciliation verdicts into loan servicing actions.	`match_run_id`, `context_id`, `mode`, `status`, `stats`, `started_at`, `completed_at`?
`studio.lerian.match_run.failed`	`matcher.match_run.failed`	A match run fails.	As `completed`, plus `failure_reason`
`studio.lerian.match_group.confirmed`	`matcher.match_group.confirmed`	A match group is confirmed.	`match_group_id`, `match_run_id`, `context_id`, `rule_id`, `transaction_ids`, `confidence`, `status`, `confirmed_at`?
`studio.lerian.match_group.unmatched`	`matcher.match_group.unmatched`	A confirmed match group is undone.	As `confirmed`, plus `previous_status`, `reason`, `unmatched_at`
`studio.lerian.fee_variance.created`	`matcher.fee_variance.created`	A fee-aware rule detects a variance between expected and actual fees.	`fee_variance_id`, `context_id`, `match_run_id`, `match_group_id`, `transaction_id`, `fee_schedule_id`, `fee_schedule_name_snapshot`, `currency`, `expected_fee`, `actual_fee`, `delta`, `variance_type`, `created_at`

Exception and dispute events

Outbox-backed except exception.assigned and the comment events, which are direct.

Event (`ce-type`)	Topic	Fires when	Key payload
`studio.lerian.exception.assigned`	`matcher.exception.assigned`	An exception is assigned to an operator.	`exception_id`, `status`, `version`, `assigned_at`
`studio.lerian.exception.resolved`	`matcher.exception.resolved`	An exception is resolved.	`exception_id`, `status`, `version`, `resolution_type`?, `transaction_id`?, `resolved_at`
`studio.lerian.exception.force_match_resolved`	`matcher.exception.force_match_resolved`	An exception is resolved by force-match with an override reason.	Base fields plus `resolution_type` (`FORCE_MATCH`), `override_reason_code`, `resolved_at`
`studio.lerian.exception.adjust_entry_resolved`	`matcher.exception.adjust_entry_resolved`	An exception is resolved by an adjustment entry.	Base fields plus `resolution_type` (`ADJUST_ENTRY`), `reason_code`, `amount`, `currency`, `resolved_at`
`studio.lerian.exception.dispatched`	`matcher.exception.dispatched`	An exception is dispatched to an external system.	`exception_id`, `target_system`, `queue`, `external_reference`, `acknowledged`, `dispatched_at`
`studio.lerian.exception.callback_processed`	`matcher.exception.callback_processed`	An external system’s callback is applied to an exception.	Base fields plus `external_system`, `external_issue_id`, `callback_type`, `processed_at`
`studio.lerian.exception_comment.added`	`matcher.exception_comment.added`	A comment is added to an exception thread.	`comment_id`, `exception_id`, `created_at`
`studio.lerian.exception_comment.deleted`	`matcher.exception_comment.deleted`	A comment is deleted.	`comment_id`, `exception_id`, `actor`, `deleted_at`
`studio.lerian.dispute.opened`	`matcher.dispute.opened`	A dispute is opened on an exception.	`dispute_id`, `exception_id`, `state`, `resolution`?, `category`, `opened_at`
`studio.lerian.dispute.won`	`matcher.dispute.won`	A dispute closes as won.	As `opened`, plus `closed_at`
`studio.lerian.dispute.lost`	`matcher.dispute.lost`	A dispute closes as lost.	As `opened`, plus `closed_at`
`studio.lerian.evidence.submitted`	`matcher.evidence.submitted`	Evidence is attached to a dispute.	`evidence_id`, `dispute_id`, `exception_id`, `has_file`, `submitted_at`

Configuration and data-intake events

All direct.

Event (`ce-type`)	Topic	Fires when	Key payload
`studio.lerian.reconciliation_context.created`	`matcher.reconciliation_context.created`	A reconciliation context is created.	`context_id`, `name`, `context_type`, `interval`, `status`, `auto_match_on_upload`, `created_at`, `tenant_id`
`studio.lerian.reconciliation_context.updated`	`matcher.reconciliation_context.updated`	A context’s metadata or lifecycle status changes.	Same schema, with `updated_at`
`studio.lerian.reconciliation_source.created`	`matcher.reconciliation_source.created`	A source (input side) is created in a context.	`context_id`, `source_id`, `name`, `source_type`, `side`, `created_at`
`studio.lerian.match_rule.created`	`matcher.match_rule.created`	A match rule is created.	`context_id`, `rule_id`, `rule_type`, `priority`, `config_hash`, `created_at`
`studio.lerian.match_rule.reordered`	`matcher.match_rule.reordered`	Rule priorities are reordered.	`context_id`, `ordered_rule_ids`, `priority_version`, `reordered_at`
`studio.lerian.fetcher_connection.synced`	`matcher.fetcher_connection.synced`	A Fetcher connection and its discovered schema snapshot are synchronized.	`connection_id`, `fetcher_connection_id`, `config_name`, `database_type`, `status`, `schema_discovered`, `last_seen_at`, `updated_at`
`studio.lerian.fetcher_connection.unreachable`	`matcher.fetcher_connection.unreachable`	A Fetcher connection becomes unreachable.	Same schema, plus `previous_status`
`studio.lerian.extraction_request.created`	`matcher.extraction_request.created`	An extraction request is created against a connection.	`extraction_request_id`, `connection_id`, `status`, `table_count`, `has_filters`, `start_date`, `end_date`, `created_at`
`studio.lerian.ingestion.completed`	`matcher.ingestion.completed`	An ingestion job completes.	`job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `transaction_count`, `date_range_start`, `date_range_end`, `completed_at`
`studio.lerian.ingestion.failed`	`matcher.ingestion.failed`	An ingestion job fails.	`job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `error_code`, `failed_at`

Governance and reporting events

Outbox-backed except the export-job family, which is direct.

Event (`ce-type`)	Topic	Fires when	Key payload
`studio.lerian.audit_log.created`	`matcher.audit_log.created`	A hash-chained audit log entry is persisted.	`audit_log_id`, `tenant_id`, `entity_type`, `entity_id`, `action`, `tenant_seq`, `hash_version`, `record_hash`, `created_at`
`studio.lerian.archive_metadata.created`	`matcher.archive_metadata.created`	The archival worker registers an archive partition.	`archive_metadata_id`, `tenant_id`, `partition_name`, `date_range_start`, `date_range_end`, `status`, `created_at`, `updated_at`, plus `checksum`?, `row_count`?, `compressed_size_bytes`?, `storage_class`?, `archived_at`?
`studio.lerian.archive.uploaded`	`matcher.archive.uploaded`	An archive is uploaded to storage.	Same schema
`studio.lerian.archive.completed`	`matcher.archive.completed`	An archival cycle completes.	Same schema
`studio.lerian.actor.pseudonymized`	`matcher.actor.pseudonymized`	An actor’s personal data is pseudonymized (GDPR/LGPD).	`actor_id`, `pseudonymized`, `display_name_status`, `email_status`, `updated_at`, `tenant_id`
`studio.lerian.export_job.created`	`matcher.export_job.created`	An export job is created.	`export_job_id`, `tenant_id`, `context_id`, `report_type`, `format`, `status`, `schema_version`, `created_at`, `expires_at`, `updated_at`
`studio.lerian.export_job.succeeded`	`matcher.export_job.succeeded`	An export job finishes writing its artifact.	Same schema, plus `file_name`?, `sha256`?, `records_written`?, `bytes_written`?, `attempts`?, `finished_at`?
`studio.lerian.export_job.failed`	`matcher.export_job.failed`	An export job fails.	Same schema, plus `error_code`, `attempts`?, `finished_at`?
`studio.lerian.export_job.expired`	`matcher.export_job.expired`	An export artifact expires and is cleaned up.	Same schema, plus `expired_at`?

Declared but not yet emitted

The catalog and manifest declare seven additional events that no code path emits today: reconciliation_context.deleted and the extraction_request lifecycle family (submitted, completed, failed, cancelled, bridged, bridge_failed). They are contract reservations — do not build consumers that depend on receiving them.

Events consumed

Matcher consumes no Kafka streaming events. Its integration inputs arrive over HTTP: file uploads, Fetcher extractions, and — when enabled — Streaming Hub webhook deliveries on POST /v1/discovery/hub/events (HMAC-signed, deduplicated by event id, disabled by default).

Overview

Midaz

Tracer

Lender

Matcher

Reporter

Fetcher

Consignado

Matcher events

Delivery policies

Matching events

Exception and dispute events

Configuration and data-intake events

Governance and reporting events

Declared but not yet emitted

Events consumed

​Delivery policies

​Matching events

​Exception and dispute events

​Configuration and data-intake events

​Governance and reporting events

​Declared but not yet emitted

​Events consumed

Delivery policies

Matching events

Exception and dispute events

Configuration and data-intake events

Governance and reporting events

Declared but not yet emitted

Events consumed