Webhooks and callbacks

Webhooks enable real-time communication between Matcher and external systems. This guide covers outbound event notifications and inbound resolution callbacks.

Overview

Matcher supports bidirectional webhook communication, keeping your operational tools in sync with every reconciliation event in real time. This reduces manual intervention, helps maintain SLA compliance, and ensures a continuous audit trail across all connected systems.

Outbound webhooks: exception routing dispatches exceptions to external targets — JIRA, ServiceNow, or an HTTP webhook endpoint you configure
Inbound callbacks: External systems notify Matcher when actions are taken

When an exception is routed to a webhook target, Matcher delivers a signed HTTP request to your endpoint. External systems like JIRA or ServiceNow can then send callbacks to update exception status or close items automatically. This two-way flow keeps your tools in sync without manual intervention. Beyond exception dispatch, Matcher publishes its full lifecycle event catalog on the platform’s streaming backbone — those events are consumed as a stream, not delivered as HTTP webhooks.

Matcher Webhooks Callbacks — Two-way flow between Matcher and external systems.

Outbound events

Matcher emits events when significant actions occur in the reconciliation process. The catalog below is published on the streaming backbone; exception events additionally reach HTTP webhook endpoints through exception routing.

Available events

Matcher’s event catalog is defined centrally. The most commonly consumed events are grouped by domain below. 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_context.deleted`	Context deleted	Downstream teardown
`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 (Fetcher)

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 Fetcher	Extraction monitoring
`extraction_request.completed`	Extraction completed with artifact	Data readiness
`extraction_request.failed`	Extraction failed	Error alerting
`extraction_request.cancelled`	Extraction cancelled	Pipeline monitoring
`extraction_request.bridged`	Extraction linked to an ingestion job	Pipeline monitoring
`extraction_request.bridge_failed`	Bridge to ingestion 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 sent to an external target	Ticket creation
`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

Webhook delivery payload

Exception dispatches to a webhook target carry a consistent payload — eventId, eventType, timestamp, the exception snapshot under data, and routing/tracing information under metadata:

{
  "eventId": "0e8f1c2a-5b6d-4f3e-9a7b-1c2d3e4f5a6b",
  "eventType": "exception.dispatched",
  "timestamp": "2026-01-20T10:30:00Z",
  "data": {
    "exceptionId": "9b2f4e6a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
    "transactionId": "7a1b3c5d-9e8f-4a2b-b6c7-d8e9f0a1b2c3",
    "severity": "HIGH",
    "status": "PENDING",
    "amount": "15000.00",
    "currency": "USD",
    "reason": "No matching ledger entry found",
    "sourceType": "LEFT",
    "createdAt": "2026-01-20T10:29:15Z",
    "dueAt": "2026-01-23T10:29:15Z"
  },
  "metadata": {
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "target": "WEBHOOK",
    "queue": "ops-review",
    "ruleName": "high-value-unmatched",
    "assignee": "ops-team"
  }
}

data.dueAt and the metadata fields traceId, queue, ruleName, and assignee are omitted when not set. Streaming catalog events (the tables above) follow their own per-event schemas on the event stream and are not delivered in this HTTP shape.

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 callback endpoint is authenticated by the X-Callback-Token header — an opaque token minted through the callback credentials surface — not by an operator JWT. All fields shown below are required; 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-Key: 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. Use the X-Idempotency-Key header to prevent duplicate processing.

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. This means you don’t need to generate a new idempotency key when retrying a failed callback — simply resend the same request and Matcher handles the recovery. The retry behavior applies only to callbacks that were marked as failed internally. Callbacks that completed successfully are still deduplicated as expected.

Callback credentials

Inbound callbacks are authenticated with an opaque bearer token that the external system sends in the X-Callback-Token header. These callback credentials are minted, listed, rotated, and revoked through a dedicated CRUD surface under /v1/exceptions/callbacks/credentials. Each credential is bound to the caller’s tenant, and only the token’s SHA-256 hash is stored server-side — the raw token is returned exactly once at mint/rotate time.

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 body is optional; provide externalSystem 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.

The raw token is shown only in the mint and rotate responses. Store it securely on receipt — it cannot be retrieved again. If it is lost or leaked, 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 (new raw token) and revokes the previous credential atomically, so external callers experience no gap when you swap the token.

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.

Webhook security

Signature verification

When a webhook shared secret is configured, Matcher signs each delivery with an HMAC-SHA256 over the raw request body and sends it in the X-Signature-256 header, formatted as sha256=<hex-digest>:

X-Signature-256: sha256=abc123...

Each delivery also carries an X-Idempotency-Key header so receivers can deduplicate retries. Verification process:

Compute HMAC-SHA256 of the raw request body using the webhook shared secret
Prefix the hex digest with sha256=
Compare (constant-time) with the X-Signature-256 header

Example (Node.js):

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
 const expectedSignature = crypto
 .createHmac('sha256', secret)
 .update(payload)
 .digest('hex');

 return `sha256=${expectedSignature}` === signature;
}

Example (Python):

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
 expected = hmac.new(
 secret.encode(),
 payload,
 hashlib.sha256
 ).hexdigest()
 return f"sha256={expected}" == signature

Network posture

Matcher deploys in your own infrastructure, so webhook deliveries originate from your deployment’s egress — there is no fixed Lerian IP range to allowlist. Serve webhook endpoints over HTTPS with a valid certificate. As an SSRF guard, Matcher refuses to deliver to private or loopback IP addresses unless the deployment explicitly allows them (development only).

Retry logic

Failed webhook deliveries are retried with exponential backoff.

Default retry policy

A failed delivery is retried up to 3 times by default. Delays follow exponential backoff from a 1-second base, with jitter added to spread retries — so the exact spacing varies from attempt to attempt rather than following a fixed ladder.

Retry conditions

Retries occur for:

HTTP 429 responses
HTTP 5xx responses
Transport errors (connection failures, timeouts)

No retry for:

Other HTTP 4xx responses

Best practices

Verify webhook signatures

Always verify the HMAC signature before processing webhook payloads. This prevents spoofed requests.

Respond quickly

Return a 2xx response within 5 seconds. Process the event asynchronously if needed.

Handle duplicates idempotently

Deliveries may arrive more than once. Deduplicate on the X-Idempotency-Key header or the payload’s eventId.

Monitor delivery health

Set up alerts for webhook failure rates. Investigate persistent failures promptly.

Overview

Guides

Matcher UI

MCP Server

Operations

Webhooks and callbacks

Overview

Outbound events

Available events

Webhook delivery payload

Inbound callbacks

Process a callback

Response

Automatic retry for failed callbacks

Callback credentials

Mint a credential

Rotate a credential

Revoke a credential

Webhook security

Signature verification

Network posture

Retry logic

Default retry policy

Retry conditions

Best practices

Next steps

Exception Routing

External Sources

​Overview

​Outbound events

​Available events

​Webhook delivery payload

​Inbound callbacks

​Process a callback

​Response

​Automatic retry for failed callbacks

​Callback credentials

​Mint a credential

​Rotate a credential

​Revoke a credential

​Webhook security

​Signature verification

​Network posture

​Retry logic

​Default retry policy

​Retry conditions

​Best practices

​Next steps

Exception Routing

External Sources

Overview

Outbound events

Available events

Webhook delivery payload

Inbound callbacks

Process a callback

Response

Automatic retry for failed callbacks

Callback credentials

Mint a credential

Rotate a credential

Revoke a credential

Webhook security

Signature verification

Network posture

Retry logic

Default retry policy

Retry conditions

Best practices

Next steps