Webhooks and callbacks

This guide covers the events Matcher publishes and the inbound callbacks that external systems send to Matcher.

Overview

Outbound events: Matcher publishes its lifecycle event catalog on the platform’s streaming backbone. Those events reach you as a stream, not as HTTP webhooks.
Inbound callbacks: External systems, such as a ticketing tool, notify Matcher when they act on an exception. Matcher then updates the exception status.

Outbound events

Matcher emits events when significant actions occur in the reconciliation process, and publishes them on the streaming backbone. Each event follows its own schema on the event stream.

Available events

The tables below list the event catalog by domain. Configuration

Event	Trigger	Typical Use
`reconciliation_context.created`	Reconciliation context created	Provisioning sync
`reconciliation_context.updated`	Context metadata or status changed	Config change tracking
`reconciliation_source.created`	Source created within a context	Source onboarding
`match_rule.created`	Match rule created	Rule change audit
`match_rule.reordered`	Rule priorities reordered	Rule change audit

Discovery

Event	Trigger	Typical Use
`fetcher_connection.synced`	Connection and schema snapshot synchronized	Discovery monitoring
`fetcher_connection.unreachable`	Connection marked unreachable	Connectivity alerting
`extraction_request.created`	Extraction request created	Extraction monitoring
`extraction_request.submitted`	Extraction accepted by the extraction engine	Extraction monitoring
`extraction_request.completed`	Extraction completed and handed to ingestion	Data readiness
`extraction_request.failed`	Extraction failed	Error alerting

Ingestion

Event	Trigger	Typical Use
`ingestion.completed`	File import finished	Data pipeline monitoring
`ingestion.failed`	File import failed	Error alerting
`transaction.ignored`	Unmatched transaction marked ignored	Audit trail

Matching

Event	Trigger	Typical Use
`match_run.completed`	Match job finished	Job monitoring, reporting
`match_run.failed`	Match job failed	Error alerting
`match_group.confirmed`	Match group confirmed	Downstream updates
`match_group.unmatched`	Confirmed match reverted	Correction tracking
`transaction.matched`	Transaction marked matched	Audit logging
`transaction.pending_review`	Non-automatic candidate needs review	Review queue triggers
`fee_variance.created`	Fee variance detected	Fee investigation

Exceptions and disputes

Event	Trigger	Typical Use
`exception.assigned`	Exception assigned to an owner	User notification
`exception.resolved`	Exception resolved	Status sync
`exception.dispatched`	Exception dispatched to a target system	Audit trail
`exception.callback_processed`	External callback processed	Status sync
`exception.force_match_resolved`	Exception resolved via force match	Approval workflows
`exception.adjust_entry_resolved`	Exception resolved via adjustment entry	Audit trail
`exception_comment.added`	Comment added to an exception	Collaboration sync
`exception_comment.deleted`	Exception comment deleted	Collaboration sync
`dispute.opened`	Dispute opened for an exception	Dispute tracking
`dispute.won`	Dispute closed as won	Status sync
`dispute.lost`	Dispute closed as lost	Status sync
`evidence.submitted`	Evidence submitted to a dispute	Dispute tracking

Governance and reporting

Event	Trigger	Typical Use
`audit_log.created`	Audit log entry appended	Compliance monitoring
`archive_metadata.created`	Archive lifecycle started	Archival monitoring
`archive.uploaded`	Archive object uploaded	Archival monitoring
`archive.completed`	Archive verified and completed	Archival monitoring
`actor.pseudonymized`	Actor mapping pseudonymized	Compliance monitoring
`export_job.created`	Export job queued	Export monitoring
`export_job.succeeded`	Export job completed	Download readiness
`export_job.failed`	Export job failed	Error alerting
`export_job.expired`	Export artifact expired	Export lifecycle

Inbound callbacks

External systems send callbacks to Matcher to update exception status after processing. The callback endpoint accepts status updates, resolution notes, and assignee changes from any external system.

Process a callback

The X-Callback-Token header authenticates the callback endpoint. An operator JWT does not authenticate it. The header carries an opaque token from the callback credentials surface. Every field below is mandatory. dueAt and updatedAt accept null, and payload can be an empty object:

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": {}
 }'

The externalSystem field identifies the external system that processed the exception. Common values include "JIRA", "SERVICENOW", or "WEBHOOK", but callbacks can report any system identifier. Omitting any of the nine required fields returns a 422.

Response

{
  "status": "accepted"
}

API Reference: Process callback

When Matcher processes a callback, it updates the exception status and records the resolution in the audit trail. The X-Idempotency header is required. Matcher reads the idempotency key only from this header. A request that carries a key only in X-Idempotency-Key or Idempotency-Key is refused with 400 (MTCH-0015), and nothing is processed. Matcher deduplicates a callback by its external system, its exception, and its key together. The same key on another exception or from another external system is a new callback.

Callback status

status moves the exception to ASSIGNED or RESOLVED. Matcher reads the value without case sensitivity.
To move the exception to ASSIGNED, send a non-blank assignee.
When status is the current status of the exception, Matcher keeps the status and updates assignee and dueAt if you send them.

Callback refusals

Status	Code	Meaning
`400`	`MTCH-0015`	The key arrived only in `X-Idempotency-Key` or `Idempotency-Key`.
`400`	`MTCH-0001`	The callback is not valid. For example, the `X-Idempotency` value is not 1 to 128 letters, digits, `:`, `_`, or `-`, or an `ASSIGNED` callback has no `assignee`.
`409`	`MTCH-0504`	Another callback with the same key is still in process. Send the request again later.
`409`	`MTCH-0505`	Matcher cannot confirm the state of an earlier callback with the same key. Send the request again later.
`429`	`MTCH-0506`	The external system sent more callbacks than its rate limit allows. Send the request again later.

An unknown or revoked callback token answers 404. When Matcher cannot check the token, it answers 503.

Automatic retry for failed callbacks

If a previous callback for the same idempotency key failed during processing, Matcher automatically attempts to reacquire the idempotency lock and reprocess the callback. You don’t need to generate a new idempotency key when retrying a failed callback. Resend the same request and Matcher handles the recovery. The retry behavior applies only to callbacks with an internal failed state. Matcher still deduplicates callbacks that completed successfully.

Callback credentials

An opaque bearer token authenticates inbound callbacks. The external system sends this token in the X-Callback-Token header. You mint, list, rotate, and revoke these callback credentials through a dedicated CRUD surface under /v1/exceptions/callbacks/credentials. Each credential belongs to the caller’s tenant. Matcher stores only the token’s SHA-256 hash server-side. The mint and rotate responses return the raw token exactly once.

Action	Method & path	Notes
Mint credential	`POST /v1/exceptions/callbacks/credentials`	Creates a credential and returns the raw token once (`201`).
List credentials	`GET /v1/exceptions/callbacks/credentials`	Lists credential metadata for the tenant (never the raw tokens).
Rotate credential	`POST /v1/exceptions/callbacks/credentials/{credentialId}/rotate`	Atomically supersedes a live credential with a freshly minted one (same label) and returns the new raw token once; the old one is revoked in the same transaction.
Revoke credential	`DELETE /v1/exceptions/callbacks/credentials/{credentialId}`	Terminally revokes a credential (`204`); append-only audited.

API Reference:

Mint a credential

The request needs a JSON body. Send {} if you do not set a label. The externalSystem field is optional. Provide it as an operator-legible label for the system this token authenticates.

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" }'

The 201 response (CredentialSecretResponse) returns:

Field	Description
`token`	Raw bearer token, surfaced once. Configure it as the `X-Callback-Token` header value in the external system.
`credentialId`	Surrogate id of the minted credential (used for rotate/revoke).
`createdAt`	Mint time (RFC 3339, UTC).
`externalSystem`	The label echoed back for confirmation.
`webhookUrlHint`	Informational inbound-callback URL shape to configure externally; the `{exceptionId}` placeholder is filled per callback.

Only the mint and rotate responses show the raw token. Store it securely on receipt. You cannot retrieve it again. If you lose or leak the token, rotate or revoke the credential.

Rotate a credential

cURL

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

Rotation returns a new CredentialSecretResponse (201, new raw token) and revokes the previous credential in the same transaction. Callbacks that still send the old token fail, so update the external system with the new token at once.

Revoke a credential

cURL

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

Revocation is terminal: the credential can no longer authenticate inbound callbacks.

Overview

Guides

Console

MCP Server

Operations

Webhooks and callbacks

Overview

Outbound events

Available events

Inbound callbacks

Process a callback

Response

Callback status

Callback refusals

Automatic retry for failed callbacks

Callback credentials

Mint a credential

Rotate a credential

Revoke a credential

Next steps

Exception Routing

External Sources

​Overview

​Outbound events

​Available events

​Inbound callbacks

​Process a callback

​Response

​Callback status

​Callback refusals

​Automatic retry for failed callbacks

​Callback credentials

​Mint a credential

​Rotate a credential

​Revoke a credential

​Next steps

Exception Routing

External Sources

Overview

Outbound events

Available events

Inbound callbacks

Process a callback

Response

Callback status

Callback refusals

Automatic retry for failed callbacks

Callback credentials

Mint a credential

Rotate a credential

Revoke a credential

Next steps