Webhooks deliver domain events (incoming-transaction.created, match.created, etc.) to your endpoints. Configure URL, subscribed events, retry policy, and optional HMAC signing for verification.

What are webhooks

Webhooks let Payment Reconciler push domain events to your application in real time. When an event occurs (e.g. a new incoming transaction is created, a match is accepted), the system sends an HTTP POST to your configured URL with the event payload. You can react by updating your UI, triggering workflows, or syncing to external systems.

Each webhook is scoped to a tenant and environment. You subscribe to specific event types and configure retry behavior for failed deliveries.

Subscribed events

Event	When it fires
`incoming-transaction.created`	New incoming transaction created
`incoming-transaction.updated`	Incoming transaction updated
`expected-transaction.created`	New expected transaction created
`expected-transaction.updated`	Expected transaction updated
`expected-transaction.deleted`	Expected transaction deleted
`match.created`	New match created (LedgerMatch returned candidates)
`match.accepted`	Match accepted
`match.rejected`	Match rejected
`data-source.sync-completed`	Stripe/EBICS sync finished successfully
`data-source.sync-failed`	Sync failed
`job.completed`	Job finished
`job.failed`	Job failed
`job.started`	Job started

Subscribe to the events you need. Each delivery includes the event type, timestamp, and entity data (e.g. transaction ID, match ID).

HMAC signing

Optionally provide a secret when creating a webhook. The system signs each payload with HMAC-SHA256 and sends the signature in a header (e.g. X-Webhook-Signature). Verify the signature on your side to ensure the request came from Payment Reconciler and was not tampered with. See Webhook Config for the header name and verification approach.

Retry and delivery

Failed deliveries (non-2xx response, timeout, network error) are retried according to the webhook's retry policy:

maxAttempts — Number of retries (default: 5)
backoffStrategy — exponential or linear
backoffIntervals — Optional custom delays in ms

A webhook-retry job periodically retries failed attempts. View delivery history via GET /webhooks/:id/deliveries to see status, response code, and error messages per attempt.

Test webhooks

Use POST /webhooks/:id/test to send a test event to your URL. Useful for verifying your endpoint is reachable and correctly verifies signatures before going live.

API Reference

For create/update parameters, retry policy schema, and request/response samples, see Webhooks in the API Reference.