Managed webhooks

Managed webhooks send payment outcome and outbound dispatch events to an HTTPS receiver in your system. Each endpoint belongs to one company and environment and has an explicit list of subscribed event types.

Available only for integrations explicitly configured by Finosu. Contact Finosu to confirm availability and configure your endpoint. Endpoint management currently requires internal staff access; it is not a public API-key management API.

Receive your first event

Create a receiver that verifies the signature on incoming POST requests.
Give Finosu its public HTTPS URL and the event types you want to receive.
Accept a signed test event, then have Finosu activate the endpoint when your business-event handler is ready.

Follow the quickstart for a runnable test receiver and setup instructions.

Choose your events

Workflow	Subscribe to
Record confirmed payments	`payment.succeeded`
Track failed payments	`payment.failed`
Reconcile returned payments	`payment.returned`
Track accepted texts	`text.sent`
Track outbound phone legs starting	`call.started`
Track accepted emails	`email.sent`

Subscriptions are explicit; there is no automatic subscription to future event types. See the event catalog for triggers, payload fields, and examples.

Event envelope

All business events use this envelope. The data object depends on type.

{
  "id": "4f6519a2-9d0c-472f-903b-d451a377bef1",
  "type": "payment.succeeded",
  "occurred_at": "2026-11-03T15:00:00+00:00",
  "environment": "production",
  "company_id": "df29fd53-3bc0-40ef-9885-4a739f97aa10",
  "subject": {
    "type": "payment",
    "id": "1ce7413e-edde-47c4-b67a-388b408619ec",
    "sequence": 123
  },
  "references": {
    "customer_reference": "CUST-123",
    "loan_reference": "LOAN-456"
  },
  "data": {
    "status": "successful",
    "amount": "100.00",
    "currency": "USD",
    "origin": "SYSTEM",
    "payment_plan_id": null,
    "gateway_charge_amount": null
  },
  "test": false
}

Field	Type	Meaning
`id`	UUID string	Event identity, stable across destinations and retries.
`type`	string	Event name from the catalog, or `webhook.test`.
`occurred_at`	ISO 8601 datetime	Capture time, not necessarily when the source action or settlement occurred.
`environment`	string	Configured deployment environment. Confirm the expected value with Finosu.
`company_id`	UUID string	Company that owns the event.
`subject.type`	string	Resource category: `payment`, `text`, `call`, `email`, or `webhook` for a test.
`subject.id`	UUID string	Finosu resource ID; not an external customer or loan reference.
`subject.sequence`	integer	Ordering value within the same company, subject type, and subject ID. Gaps are allowed.
`references.customer_reference`	string or null	Your external customer reference, when available.
`references.loan_reference`	string or null	Your external loan reference, when available. Never infer a missing reference.
`data`	object	Event-specific fields.
`test`	boolean	True for test-customer events and synthetic endpoint tests. Never apply test events to live borrower records.

Decimal monetary amounts are JSON strings; use decimal arithmetic. IDs and references are opaque. Do not convert references to numbers.

Payload compatibility

Receivers should tolerate additional object fields and handle unrecognized event names without applying business effects. The origin string may gain new values. Retries preserve the stored event payload; they do not rebuild old events from the latest source state. See delivery behavior for deduplication and recovery rules.

Existing integration contracts

Contract	Direction	Documentation
Managed webhooks	Finosu → your receiver	These guides; signed events with a common envelope.
Call-result callback	Finosu → your receiver	Call results; separately configured payload and retry rules.
Transfer-note callback	Finosu → your receiver	Transfer notes; integration-specific delivery.
Customer upsert	Your system → Finosu	Customer upsert; an authenticated inbound API request.

Existing integrations keep their configured contracts. Creating a managed endpoint does not replace an existing callback or disable its deliveries.

Next steps

Quickstart: receive a signed test event.
Event catalog: choose events and map their data.
Verify signatures: authenticate each request.
Delivery and retries: handle duplicates and failures.

Subscription timing

Subscriptions apply to future source notifications. Activating an endpoint or adding an event type does not backfill earlier events, including delayed or replayed notifications. Removing and re-adding a type starts a new subscription window. Pausing and resuming preserves existing subscriptions and queued deliveries. Events with no eligible endpoint create no delivery record.

API Documentation

Core Resources

Origination

Collections

Managed webhooks

Receive your first event

Choose your events

Event envelope

Payload compatibility

Existing integration contracts

Next steps

Subscription timing