> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finosu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed webhooks

> Receive signed events from Finosu.

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.

> [!NOTE]
>
> 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

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

Follow the [quickstart](https://docs.finosu.com/api-reference/webhooks/quickstart.md) 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](https://docs.finosu.com/api-reference/webhooks/events.md) for triggers,
payload fields, and examples.

## Event envelope

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

```json theme={null}
{
  "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](https://docs.finosu.com/api-reference/webhooks/receiving.md)
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](https://docs.finosu.com/api-reference/endpoint/calls/webhook.md); separately configured payload and retry rules. |
| Transfer-note callback | Finosu → your receiver | [Transfer notes](https://docs.finosu.com/api-reference/endpoint/transfer-notes/transfer-note.md); integration-specific delivery. |
| Customer upsert | Your system → Finosu | [Customer upsert](https://docs.finosu.com/api-reference/endpoint/customers/webhook.md); 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](https://docs.finosu.com/api-reference/webhooks/quickstart.md): receive a signed test event.
* [Event catalog](https://docs.finosu.com/api-reference/webhooks/events.md): choose events and map their data.
* [Verify signatures](https://docs.finosu.com/api-reference/webhooks/verification.md): authenticate each request.
* [Delivery and retries](https://docs.finosu.com/api-reference/webhooks/receiving.md): 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.