Event catalog

Managed webhooks are available to integrations explicitly configured by Finosu. Contact Finosu to confirm eligibility and configure your company. Select individual subscriptions within Payments, Texts, Calls, and Emails. Setup tests are not subscriptions. This reference and the webhook editor use the same backend catalog. The sender validates the complete envelope and event data against that contract before saving a delivery. Examples below contain fictional identifiers. Receivers should tolerate additional fields for forward compatibility. The JSON schemas below are strict sender-side contracts: additionalProperties: false prevents accidental disclosure when Finosu creates a delivery. Receivers using these schemas must allow unknown properties at every object level, including nested objects and $defs, while still validating known fields, signatures, company, and environment.

Request and acceptance

Finosu sends an HTTPS POST with Content-Type: application/json, X-Finosu-Signature: t=<unix-seconds>,v1=<hmac>, and an Idempotency-Key that identifies the endpoint delivery. An optional configured bearer token is sent in Authorization. Verify the raw-body signature, check company and environment, then durably deduplicate and enqueue before returning 2xx. Return 2xx for an already accepted duplicate. See delivery and retries for failures, ordering, pauses, and retry limits. These events never authorize another charge or send. occurred_at is consumer capture time. Text/email events separately expose data.sent_at; calls expose data.started_at for their supported source signal. A successful dispatch does not prove a text/email was delivered, a borrower answered, or content was read. Publication gaps before the delivery queue are not repaired by HTTP retries; there is no historical catch-up API. Test-customer events use the same event names and subscriptions with test: true. Accept and deduplicate them, but never apply them to live accounts. They do not verify endpoint setup or bypass activation/pause. The separate webhook.test event remains the explicit synthetic endpoint-verification signal.

Common envelope

Field	Type	Required	Meaning
`id`	uuid	Yes	Event ID shared across endpoint copies; retained on retry.
`type`	string	Yes	Event name from this catalog.
`occurred_at`	date-time	Yes	Consumer capture time in UTC; not source commit time.
`environment`	string	Yes	Finosu environment; validate against your configured environment.
`company_id`	uuid	Yes	Owning company; validate against your configured company.
`subject`	object	Yes	See the nested schema below.
`references`	object	Yes	See the nested schema below.
`data`	object	Yes	See the nested schema below.
`test`	boolean	Yes	True for a test-customer event or an explicit synthetic endpoint test. Test-customer events follow ordinary subscriptions and do not verify an endpoint.

subject

Field	Type	Required	Meaning
`type`	`payment` or `text` or `call` or `email` or `webhook`	Yes	Resource category.
`id`	uuid	Yes	Stable Finosu resource ID. Email dispatch uses an opaque send identity.
`sequence`	integer	Yes	Compare only within the same company and subject; not a global catch-up cursor.

references

Field	Type	Required	Meaning
`customer_reference`	string or null	Yes	Your customer reference, or null.
`loan_reference`	string or null	Yes	Your exact associated loan reference, or null. Never inferred from another loan.

Events

Group	Event	Description
Payments	`payment.succeeded`	A payment has a confirmed successful outcome. Pending ACH submission is excluded.
Payments	`payment.failed`	A payment has a confirmed failed outcome. This does not authorize another charge.
Payments	`payment.returned`	A previously recorded payment was returned. Its identity and origin are retained.
Texts	`text.sent`	An outbound text was accepted by the sending provider.
Calls	`call.started`	An outbound call’s phone leg started dialing or became active.
Emails	`email.sent`	An outbound email was accepted by the sending provider.
Setup	`webhook.test`	Synthetic endpoint verification.

payment.succeeded

Group: Payments. Subscribable: Yes. A payment has a confirmed successful outcome. Pending ACH submission is excluded. When: A supported payment notification is consumed and the persisted transaction is SUCCESSFUL. Use for: Reconcile a confirmed successful payment allocation. Coverage and limits: The consumer reads current committed state. A return can supersede an unconsumed success. Pending ACH, deleted records, test loans for non-test customers, and invalid customer/loan/company scope are excluded. Test-customer outcomes use normal subscriptions with test=true; never apply them to live accounts. Publication failures and exhausted consumer retries can lose notifications before enqueue. No historical backfill or catch-up API. Never initiate another debit from these events.

Data fields

Field	Type	Required	Meaning
`status`	`successful`	Yes	Confirmed successful payment.
`amount`	string	Yes	Decimal string allocated to this transaction.
`currency`	string	Yes	Currency recorded for the transaction.
`origin`	string	Yes	Recorded source provenance; values are not a closed catalog.
`payment_plan_id`	uuid or null	Yes	Associated Finosu payment plan ID, or null.
`gateway_charge_amount`	string or null	No	Grouped provider debit amount, when recorded. Never sum once per allocation.

Complete example

{
  "id": "4f6519a2-9d0c-472f-903b-d451a377bef1",
  "type": "payment.succeeded",
  "occurred_at": "2026-11-04T15:00:01Z",
  "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
}

payment.failed

Group: Payments. Subscribable: Yes. A payment has a confirmed failed outcome. This does not authorize another charge. When: A supported payment notification is consumed and the persisted transaction is FAILED. Use for: Reconcile a failed payment attempt without submitting another charge. Coverage and limits: The consumer reads current committed state. A return can supersede an unconsumed success. Pending ACH, deleted records, test loans for non-test customers, and invalid customer/loan/company scope are excluded. Test-customer outcomes use normal subscriptions with test=true; never apply them to live accounts. Publication failures and exhausted consumer retries can lose notifications before enqueue. No historical backfill or catch-up API. Never initiate another debit from these events.

Data fields

Field	Type	Required	Meaning
`status`	`failed`	Yes	Confirmed failed payment.
`amount`	string	Yes	Decimal string allocated to this transaction.
`currency`	string	Yes	Currency recorded for the transaction.
`origin`	string	Yes	Recorded source provenance; values are not a closed catalog.
`payment_plan_id`	uuid or null	Yes	Associated Finosu payment plan ID, or null.
`gateway_charge_amount`	string or null	No	Grouped provider debit amount, when recorded. Never sum once per allocation.

Complete example

{
  "id": "4f6519a2-9d0c-472f-903b-d451a377bef1",
  "type": "payment.failed",
  "occurred_at": "2026-11-04T15:00:01Z",
  "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": "failed",
    "amount": "100.00",
    "currency": "USD",
    "origin": "SYSTEM",
    "payment_plan_id": null,
    "gateway_charge_amount": null
  },
  "test": false
}

payment.returned

Group: Payments. Subscribable: Yes. A previously recorded payment was returned. Its identity and origin are retained. When: A return notification is consumed and the persisted transaction is RETURNED. Use for: Update the same payment’s recorded outcome to returned. Coverage and limits: The consumer reads current committed state. A return can supersede an unconsumed success. Pending ACH, deleted records, test loans for non-test customers, and invalid customer/loan/company scope are excluded. Test-customer outcomes use normal subscriptions with test=true; never apply them to live accounts. Publication failures and exhausted consumer retries can lose notifications before enqueue. No historical backfill or catch-up API. Never initiate another debit from these events.

Data fields

Field	Type	Required	Meaning
`status`	`returned`	Yes	Confirmed returned payment.
`amount`	string	Yes	Decimal string allocated to this transaction.
`currency`	string	Yes	Currency recorded for the transaction.
`origin`	string	Yes	Recorded source provenance; values are not a closed catalog.
`payment_plan_id`	uuid or null	Yes	Associated Finosu payment plan ID, or null.
`gateway_charge_amount`	string or null	No	Grouped provider debit amount, when recorded. Never sum once per allocation.

Complete example

{
  "id": "4f6519a2-9d0c-472f-903b-d451a377bef1",
  "type": "payment.returned",
  "occurred_at": "2026-11-04T15:00:01Z",
  "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": "returned",
    "amount": "100.00",
    "currency": "USD",
    "origin": "SYSTEM",
    "payment_plan_id": null,
    "gateway_charge_amount": null
  },
  "test": false
}

text.sent

Group: Texts. Subscribable: Yes. An outbound text was accepted by the sending provider. When: The shared outbound text send path commits a successful provider acceptance, then the listener requires a saved outbound message with a provider message ID, current sent or delivered status, and valid tenant scope. Use for: Track an accepted outbound text using its Finosu message ID. Coverage and limits: Reports dispatch only, not delivery, answer, or engagement. Deleted customers and invalid tenant/loan scope are excluded. Content, recipients, credentials, and provider responses are omitted. Only the supported producer paths emit notifications; direct database writes and historical sends do not. Test-customer events use normal subscriptions with test=true; never apply them to live accounts. Publication failures and exhausted consumer retries can lose notifications before enqueue. Successful integrations that omit a provider message ID are not covered. A later failed status can suppress a delayed notification. Text loan references are null; no loan is guessed.

Data fields

Field	Type	Required	Meaning
`status`	`sent`	Yes	The sending provider accepted the message. This does not prove delivery or reading.
`sent_at`	date-time	Yes	Time of the supported successful-send signal, in UTC.

Complete example

{
  "id": "4f6519a2-9d0c-472f-903b-d451a377bef1",
  "type": "text.sent",
  "occurred_at": "2026-11-04T15:00:01Z",
  "environment": "production",
  "company_id": "df29fd53-3bc0-40ef-9885-4a739f97aa10",
  "subject": {
    "type": "text",
    "id": "1ce7413e-edde-47c4-b67a-388b408619ec",
    "sequence": 123
  },
  "references": {
    "customer_reference": "CUST-123",
    "loan_reference": null
  },
  "data": {
    "status": "sent",
    "sent_at": "2026-11-04T15:00:00Z"
  },
  "test": false
}

call.started

Group: Calls. Subscribable: Yes. An outbound call’s phone leg started dialing or became active. When: An authenticated phone-participant join reports dialing, ringing, or active for an outbound call, matching its acknowledged or saved pre-dispatch room, trunk, and recipient. Use for: Track the start of the outbound phone leg using the Finosu call ID. Coverage and limits: Reports dispatch only, not delivery, answer, or engagement. Deleted customers and invalid tenant/loan scope are excluded. Content, recipients, credentials, and provider responses are omitted. Only the supported producer paths emit notifications; direct database writes and historical sends do not. Test-customer events use normal subscriptions with test=true; never apply them to live accounts. Publication failures and exhausted consumer retries can lose notifications before enqueue. Queueing, agent dispatch acknowledgment, browser audio, room creation, and the preliminary call status alone do not qualify. Early joins can match the saved pre-dispatch room. Notification acceptance requires durable broker acknowledgment; failures permit provider notification retries without redialing. Calls without a matching join or with exhausted provider retries are not covered.

Data fields

Field	Type	Required	Meaning
`status`	`started`	Yes	The outbound phone leg started. This does not prove a human answer or completed conversation.
`started_at`	date-time	Yes	Time of the supported phone-participant signal, in UTC.

Complete example

{
  "id": "4f6519a2-9d0c-472f-903b-d451a377bef1",
  "type": "call.started",
  "occurred_at": "2026-11-04T15:00:01Z",
  "environment": "production",
  "company_id": "df29fd53-3bc0-40ef-9885-4a739f97aa10",
  "subject": {
    "type": "call",
    "id": "1ce7413e-edde-47c4-b67a-388b408619ec",
    "sequence": 123
  },
  "references": {
    "customer_reference": "CUST-123",
    "loan_reference": "LOAN-456"
  },
  "data": {
    "status": "started",
    "started_at": "2026-11-04T15:00:00Z"
  },
  "test": false
}

email.sent

Group: Emails. Subscribable: Yes. An outbound email was accepted by the sending provider. When: A successful shared email-pipeline completion notification matches a persisted successful-send audit for the same company, customer, loan, recipient, and provider message. Use for: Track an accepted outbound email using a stable opaque send identity. Coverage and limits: Reports dispatch only, not delivery, answer, or engagement. Deleted customers and invalid tenant/loan scope are excluded. Content, recipients, credentials, and provider responses are omitted. Only the supported producer paths emit notifications; direct database writes and historical sends do not. Test-customer events use normal subscriptions with test=true; never apply them to live accounts. Publication failures and exhausted consumer retries can lose notifications before enqueue. Skipped, deferred, failed, bounced, customerless, and unaudited sends are excluded. Email sends outside the shared completion-event path are not covered.

Data fields

Field	Type	Required	Meaning
`status`	`sent`	Yes	The sending provider accepted the message. This does not prove delivery or reading.
`sent_at`	date-time	Yes	Time of the supported successful-send signal, in UTC.

Complete example

{
  "id": "4f6519a2-9d0c-472f-903b-d451a377bef1",
  "type": "email.sent",
  "occurred_at": "2026-11-04T15:00:01Z",
  "environment": "production",
  "company_id": "df29fd53-3bc0-40ef-9885-4a739f97aa10",
  "subject": {
    "type": "email",
    "id": "1ce7413e-edde-47c4-b67a-388b408619ec",
    "sequence": 123
  },
  "references": {
    "customer_reference": "CUST-123",
    "loan_reference": "LOAN-456"
  },
  "data": {
    "status": "sent",
    "sent_at": "2026-11-04T15:00:00Z"
  },
  "test": false
}

webhook.test

Group: Setup. Subscribable: No. Synthetic endpoint verification. When: Staff explicitly sends a synthetic test for the current endpoint configuration. Use for: Verify authentication and receiver acceptance before activation. Coverage and limits: Not a business subscription. Contains no borrower data. A test for an older configuration cannot verify a newer one.

Data fields

Field	Type	Required	Meaning
`message`	string	Yes	Synthetic setup message containing no borrower data.

Complete example

{
  "id": "4f6519a2-9d0c-472f-903b-d451a377bef1",
  "type": "webhook.test",
  "occurred_at": "2026-11-04T15:00:01Z",
  "environment": "production",
  "company_id": "df29fd53-3bc0-40ef-9885-4a739f97aa10",
  "subject": {
    "type": "webhook",
    "id": "1ce7413e-edde-47c4-b67a-388b408619ec",
    "sequence": 123
  },
  "references": {
    "customer_reference": null,
    "loan_reference": null
  },
  "data": {
    "message": "Synthetic Finosu webhook test. No borrower data."
  },
  "test": true
}

API Documentation

Core Resources

Origination

Collections

Request and acceptance

Common envelope

subject

references

Events

payment.succeeded

Data fields

Complete example

payment.failed

Data fields

Complete example

payment.returned

Data fields

Complete example

text.sent

Data fields

Complete example

call.started

Data fields

Complete example

email.sent

Data fields

Complete example

webhook.test

Data fields

Complete example