> ## 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.

# Event catalog

> Grouped events, triggers, complete payloads, field requirements, and JSON schemas.

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](https://docs.finosu.com/api-reference/webhooks/verification.md),
check company and environment, then durably deduplicate and enqueue before returning
`2xx`. Return `2xx` for an already accepted duplicate. See
[delivery and retries](https://docs.finosu.com/api-reference/webhooks/receiving.md) 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`](#paymentsucceeded) | A payment has a confirmed successful outcome. Pending ACH submission is excluded. |
| Payments | [`payment.failed`](#paymentfailed) | A payment has a confirmed failed outcome. This does not authorize another charge. |
| Payments | [`payment.returned`](#paymentreturned) | A previously recorded payment was returned. Its identity and origin are retained. |
| Texts | [`text.sent`](#textsent) | An outbound text was accepted by the sending provider. |
| Calls | [`call.started`](#callstarted) | An outbound call's phone leg started dialing or became active. |
| Emails | [`email.sent`](#emailsent) | An outbound email was accepted by the sending provider. |
| Setup | [`webhook.test`](#webhooktest) | 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

```json theme={null}
{
  "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
}
```

<details>
  <summary>Complete JSON Schema</summary>

  ```json theme={null}
  {
    "$defs": {
      "References": {
        "additionalProperties": false,
        "properties": {
          "customer_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your customer reference, or null.",
            "title": "Customer Reference"
          },
          "loan_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your exact associated loan reference, or null. Never inferred from another loan.",
            "title": "Loan Reference"
          }
        },
        "required": [
          "customer_reference",
          "loan_reference"
        ],
        "title": "References",
        "type": "object"
      },
      "Subject": {
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "const": "payment"
          },
          "id": {
            "description": "Stable Finosu resource ID. Email dispatch uses an opaque send identity.",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "sequence": {
            "description": "Compare only within the same company and subject; not a global catch-up cursor.",
            "minimum": 1,
            "title": "Sequence",
            "type": "integer"
          }
        },
        "required": [
          "type",
          "id",
          "sequence"
        ],
        "title": "Subject",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "properties": {
      "id": {
        "description": "Event ID shared across endpoint copies; retained on retry.",
        "format": "uuid",
        "title": "Id",
        "type": "string"
      },
      "type": {
        "description": "Event name from this catalog.",
        "title": "Type",
        "type": "string",
        "const": "payment.succeeded"
      },
      "occurred_at": {
        "description": "Consumer capture time in UTC; not source commit time.",
        "format": "date-time",
        "title": "Occurred At",
        "type": "string"
      },
      "environment": {
        "description": "Finosu environment; validate against your configured environment.",
        "title": "Environment",
        "type": "string"
      },
      "company_id": {
        "description": "Owning company; validate against your configured company.",
        "format": "uuid",
        "title": "Company Id",
        "type": "string"
      },
      "subject": {
        "$ref": "#/$defs/Subject"
      },
      "references": {
        "$ref": "#/$defs/References"
      },
      "data": {
        "additionalProperties": false,
        "properties": {
          "status": {
            "const": "successful",
            "description": "Confirmed successful payment.",
            "title": "Status",
            "type": "string"
          },
          "amount": {
            "description": "Decimal string allocated to this transaction.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Amount",
            "type": "string"
          },
          "currency": {
            "description": "Currency recorded for the transaction.",
            "title": "Currency",
            "type": "string"
          },
          "origin": {
            "description": "Recorded source provenance; values are not a closed catalog.",
            "title": "Origin",
            "type": "string"
          },
          "payment_plan_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Associated Finosu payment plan ID, or null.",
            "title": "Payment Plan Id"
          },
          "gateway_charge_amount": {
            "anyOf": [
              {
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Grouped provider debit amount, when recorded. Never sum once per allocation.",
            "title": "Gateway Charge Amount"
          }
        },
        "required": [
          "status",
          "amount",
          "currency",
          "origin",
          "payment_plan_id"
        ],
        "title": "SuccessfulPaymentData",
        "type": "object"
      },
      "test": {
        "description": "True for a test-customer event or an explicit synthetic endpoint test. Test-customer events follow ordinary subscriptions and do not verify an endpoint.",
        "title": "Test",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "type",
      "occurred_at",
      "environment",
      "company_id",
      "subject",
      "references",
      "data",
      "test"
    ],
    "title": "WebhookEnvelope",
    "type": "object"
  }
  ```
</details>

## 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

```json theme={null}
{
  "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
}
```

<details>
  <summary>Complete JSON Schema</summary>

  ```json theme={null}
  {
    "$defs": {
      "References": {
        "additionalProperties": false,
        "properties": {
          "customer_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your customer reference, or null.",
            "title": "Customer Reference"
          },
          "loan_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your exact associated loan reference, or null. Never inferred from another loan.",
            "title": "Loan Reference"
          }
        },
        "required": [
          "customer_reference",
          "loan_reference"
        ],
        "title": "References",
        "type": "object"
      },
      "Subject": {
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "const": "payment"
          },
          "id": {
            "description": "Stable Finosu resource ID. Email dispatch uses an opaque send identity.",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "sequence": {
            "description": "Compare only within the same company and subject; not a global catch-up cursor.",
            "minimum": 1,
            "title": "Sequence",
            "type": "integer"
          }
        },
        "required": [
          "type",
          "id",
          "sequence"
        ],
        "title": "Subject",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "properties": {
      "id": {
        "description": "Event ID shared across endpoint copies; retained on retry.",
        "format": "uuid",
        "title": "Id",
        "type": "string"
      },
      "type": {
        "description": "Event name from this catalog.",
        "title": "Type",
        "type": "string",
        "const": "payment.failed"
      },
      "occurred_at": {
        "description": "Consumer capture time in UTC; not source commit time.",
        "format": "date-time",
        "title": "Occurred At",
        "type": "string"
      },
      "environment": {
        "description": "Finosu environment; validate against your configured environment.",
        "title": "Environment",
        "type": "string"
      },
      "company_id": {
        "description": "Owning company; validate against your configured company.",
        "format": "uuid",
        "title": "Company Id",
        "type": "string"
      },
      "subject": {
        "$ref": "#/$defs/Subject"
      },
      "references": {
        "$ref": "#/$defs/References"
      },
      "data": {
        "additionalProperties": false,
        "properties": {
          "status": {
            "const": "failed",
            "description": "Confirmed failed payment.",
            "title": "Status",
            "type": "string"
          },
          "amount": {
            "description": "Decimal string allocated to this transaction.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Amount",
            "type": "string"
          },
          "currency": {
            "description": "Currency recorded for the transaction.",
            "title": "Currency",
            "type": "string"
          },
          "origin": {
            "description": "Recorded source provenance; values are not a closed catalog.",
            "title": "Origin",
            "type": "string"
          },
          "payment_plan_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Associated Finosu payment plan ID, or null.",
            "title": "Payment Plan Id"
          },
          "gateway_charge_amount": {
            "anyOf": [
              {
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Grouped provider debit amount, when recorded. Never sum once per allocation.",
            "title": "Gateway Charge Amount"
          }
        },
        "required": [
          "status",
          "amount",
          "currency",
          "origin",
          "payment_plan_id"
        ],
        "title": "FailedPaymentData",
        "type": "object"
      },
      "test": {
        "description": "True for a test-customer event or an explicit synthetic endpoint test. Test-customer events follow ordinary subscriptions and do not verify an endpoint.",
        "title": "Test",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "type",
      "occurred_at",
      "environment",
      "company_id",
      "subject",
      "references",
      "data",
      "test"
    ],
    "title": "WebhookEnvelope",
    "type": "object"
  }
  ```
</details>

## 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

```json theme={null}
{
  "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
}
```

<details>
  <summary>Complete JSON Schema</summary>

  ```json theme={null}
  {
    "$defs": {
      "References": {
        "additionalProperties": false,
        "properties": {
          "customer_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your customer reference, or null.",
            "title": "Customer Reference"
          },
          "loan_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your exact associated loan reference, or null. Never inferred from another loan.",
            "title": "Loan Reference"
          }
        },
        "required": [
          "customer_reference",
          "loan_reference"
        ],
        "title": "References",
        "type": "object"
      },
      "Subject": {
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "const": "payment"
          },
          "id": {
            "description": "Stable Finosu resource ID. Email dispatch uses an opaque send identity.",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "sequence": {
            "description": "Compare only within the same company and subject; not a global catch-up cursor.",
            "minimum": 1,
            "title": "Sequence",
            "type": "integer"
          }
        },
        "required": [
          "type",
          "id",
          "sequence"
        ],
        "title": "Subject",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "properties": {
      "id": {
        "description": "Event ID shared across endpoint copies; retained on retry.",
        "format": "uuid",
        "title": "Id",
        "type": "string"
      },
      "type": {
        "description": "Event name from this catalog.",
        "title": "Type",
        "type": "string",
        "const": "payment.returned"
      },
      "occurred_at": {
        "description": "Consumer capture time in UTC; not source commit time.",
        "format": "date-time",
        "title": "Occurred At",
        "type": "string"
      },
      "environment": {
        "description": "Finosu environment; validate against your configured environment.",
        "title": "Environment",
        "type": "string"
      },
      "company_id": {
        "description": "Owning company; validate against your configured company.",
        "format": "uuid",
        "title": "Company Id",
        "type": "string"
      },
      "subject": {
        "$ref": "#/$defs/Subject"
      },
      "references": {
        "$ref": "#/$defs/References"
      },
      "data": {
        "additionalProperties": false,
        "properties": {
          "status": {
            "const": "returned",
            "description": "Confirmed returned payment.",
            "title": "Status",
            "type": "string"
          },
          "amount": {
            "description": "Decimal string allocated to this transaction.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Amount",
            "type": "string"
          },
          "currency": {
            "description": "Currency recorded for the transaction.",
            "title": "Currency",
            "type": "string"
          },
          "origin": {
            "description": "Recorded source provenance; values are not a closed catalog.",
            "title": "Origin",
            "type": "string"
          },
          "payment_plan_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Associated Finosu payment plan ID, or null.",
            "title": "Payment Plan Id"
          },
          "gateway_charge_amount": {
            "anyOf": [
              {
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Grouped provider debit amount, when recorded. Never sum once per allocation.",
            "title": "Gateway Charge Amount"
          }
        },
        "required": [
          "status",
          "amount",
          "currency",
          "origin",
          "payment_plan_id"
        ],
        "title": "ReturnedPaymentData",
        "type": "object"
      },
      "test": {
        "description": "True for a test-customer event or an explicit synthetic endpoint test. Test-customer events follow ordinary subscriptions and do not verify an endpoint.",
        "title": "Test",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "type",
      "occurred_at",
      "environment",
      "company_id",
      "subject",
      "references",
      "data",
      "test"
    ],
    "title": "WebhookEnvelope",
    "type": "object"
  }
  ```
</details>

## 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

```json theme={null}
{
  "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
}
```

<details>
  <summary>Complete JSON Schema</summary>

  ```json theme={null}
  {
    "$defs": {
      "References": {
        "additionalProperties": false,
        "properties": {
          "customer_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your customer reference, or null.",
            "title": "Customer Reference"
          },
          "loan_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your exact associated loan reference, or null. Never inferred from another loan.",
            "title": "Loan Reference"
          }
        },
        "required": [
          "customer_reference",
          "loan_reference"
        ],
        "title": "References",
        "type": "object"
      },
      "Subject": {
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "const": "text"
          },
          "id": {
            "description": "Stable Finosu resource ID. Email dispatch uses an opaque send identity.",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "sequence": {
            "description": "Compare only within the same company and subject; not a global catch-up cursor.",
            "minimum": 1,
            "title": "Sequence",
            "type": "integer"
          }
        },
        "required": [
          "type",
          "id",
          "sequence"
        ],
        "title": "Subject",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "properties": {
      "id": {
        "description": "Event ID shared across endpoint copies; retained on retry.",
        "format": "uuid",
        "title": "Id",
        "type": "string"
      },
      "type": {
        "description": "Event name from this catalog.",
        "title": "Type",
        "type": "string",
        "const": "text.sent"
      },
      "occurred_at": {
        "description": "Consumer capture time in UTC; not source commit time.",
        "format": "date-time",
        "title": "Occurred At",
        "type": "string"
      },
      "environment": {
        "description": "Finosu environment; validate against your configured environment.",
        "title": "Environment",
        "type": "string"
      },
      "company_id": {
        "description": "Owning company; validate against your configured company.",
        "format": "uuid",
        "title": "Company Id",
        "type": "string"
      },
      "subject": {
        "$ref": "#/$defs/Subject"
      },
      "references": {
        "$ref": "#/$defs/References"
      },
      "data": {
        "additionalProperties": false,
        "properties": {
          "status": {
            "const": "sent",
            "description": "The sending provider accepted the message. This does not prove delivery or reading.",
            "title": "Status",
            "type": "string"
          },
          "sent_at": {
            "description": "Time of the supported successful-send signal, in UTC.",
            "format": "date-time",
            "title": "Sent At",
            "type": "string"
          }
        },
        "required": [
          "status",
          "sent_at"
        ],
        "title": "SentData",
        "type": "object"
      },
      "test": {
        "description": "True for a test-customer event or an explicit synthetic endpoint test. Test-customer events follow ordinary subscriptions and do not verify an endpoint.",
        "title": "Test",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "type",
      "occurred_at",
      "environment",
      "company_id",
      "subject",
      "references",
      "data",
      "test"
    ],
    "title": "WebhookEnvelope",
    "type": "object"
  }
  ```
</details>

## 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

```json theme={null}
{
  "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
}
```

<details>
  <summary>Complete JSON Schema</summary>

  ```json theme={null}
  {
    "$defs": {
      "References": {
        "additionalProperties": false,
        "properties": {
          "customer_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your customer reference, or null.",
            "title": "Customer Reference"
          },
          "loan_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your exact associated loan reference, or null. Never inferred from another loan.",
            "title": "Loan Reference"
          }
        },
        "required": [
          "customer_reference",
          "loan_reference"
        ],
        "title": "References",
        "type": "object"
      },
      "Subject": {
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "const": "call"
          },
          "id": {
            "description": "Stable Finosu resource ID. Email dispatch uses an opaque send identity.",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "sequence": {
            "description": "Compare only within the same company and subject; not a global catch-up cursor.",
            "minimum": 1,
            "title": "Sequence",
            "type": "integer"
          }
        },
        "required": [
          "type",
          "id",
          "sequence"
        ],
        "title": "Subject",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "properties": {
      "id": {
        "description": "Event ID shared across endpoint copies; retained on retry.",
        "format": "uuid",
        "title": "Id",
        "type": "string"
      },
      "type": {
        "description": "Event name from this catalog.",
        "title": "Type",
        "type": "string",
        "const": "call.started"
      },
      "occurred_at": {
        "description": "Consumer capture time in UTC; not source commit time.",
        "format": "date-time",
        "title": "Occurred At",
        "type": "string"
      },
      "environment": {
        "description": "Finosu environment; validate against your configured environment.",
        "title": "Environment",
        "type": "string"
      },
      "company_id": {
        "description": "Owning company; validate against your configured company.",
        "format": "uuid",
        "title": "Company Id",
        "type": "string"
      },
      "subject": {
        "$ref": "#/$defs/Subject"
      },
      "references": {
        "$ref": "#/$defs/References"
      },
      "data": {
        "additionalProperties": false,
        "properties": {
          "status": {
            "const": "started",
            "description": "The outbound phone leg started. This does not prove a human answer or completed conversation.",
            "title": "Status",
            "type": "string"
          },
          "started_at": {
            "description": "Time of the supported phone-participant signal, in UTC.",
            "format": "date-time",
            "title": "Started At",
            "type": "string"
          }
        },
        "required": [
          "status",
          "started_at"
        ],
        "title": "CallStartedData",
        "type": "object"
      },
      "test": {
        "description": "True for a test-customer event or an explicit synthetic endpoint test. Test-customer events follow ordinary subscriptions and do not verify an endpoint.",
        "title": "Test",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "type",
      "occurred_at",
      "environment",
      "company_id",
      "subject",
      "references",
      "data",
      "test"
    ],
    "title": "WebhookEnvelope",
    "type": "object"
  }
  ```
</details>

## 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

```json theme={null}
{
  "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
}
```

<details>
  <summary>Complete JSON Schema</summary>

  ```json theme={null}
  {
    "$defs": {
      "References": {
        "additionalProperties": false,
        "properties": {
          "customer_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your customer reference, or null.",
            "title": "Customer Reference"
          },
          "loan_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your exact associated loan reference, or null. Never inferred from another loan.",
            "title": "Loan Reference"
          }
        },
        "required": [
          "customer_reference",
          "loan_reference"
        ],
        "title": "References",
        "type": "object"
      },
      "Subject": {
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "const": "email"
          },
          "id": {
            "description": "Stable Finosu resource ID. Email dispatch uses an opaque send identity.",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "sequence": {
            "description": "Compare only within the same company and subject; not a global catch-up cursor.",
            "minimum": 1,
            "title": "Sequence",
            "type": "integer"
          }
        },
        "required": [
          "type",
          "id",
          "sequence"
        ],
        "title": "Subject",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "properties": {
      "id": {
        "description": "Event ID shared across endpoint copies; retained on retry.",
        "format": "uuid",
        "title": "Id",
        "type": "string"
      },
      "type": {
        "description": "Event name from this catalog.",
        "title": "Type",
        "type": "string",
        "const": "email.sent"
      },
      "occurred_at": {
        "description": "Consumer capture time in UTC; not source commit time.",
        "format": "date-time",
        "title": "Occurred At",
        "type": "string"
      },
      "environment": {
        "description": "Finosu environment; validate against your configured environment.",
        "title": "Environment",
        "type": "string"
      },
      "company_id": {
        "description": "Owning company; validate against your configured company.",
        "format": "uuid",
        "title": "Company Id",
        "type": "string"
      },
      "subject": {
        "$ref": "#/$defs/Subject"
      },
      "references": {
        "$ref": "#/$defs/References"
      },
      "data": {
        "additionalProperties": false,
        "properties": {
          "status": {
            "const": "sent",
            "description": "The sending provider accepted the message. This does not prove delivery or reading.",
            "title": "Status",
            "type": "string"
          },
          "sent_at": {
            "description": "Time of the supported successful-send signal, in UTC.",
            "format": "date-time",
            "title": "Sent At",
            "type": "string"
          }
        },
        "required": [
          "status",
          "sent_at"
        ],
        "title": "SentData",
        "type": "object"
      },
      "test": {
        "description": "True for a test-customer event or an explicit synthetic endpoint test. Test-customer events follow ordinary subscriptions and do not verify an endpoint.",
        "title": "Test",
        "type": "boolean"
      }
    },
    "required": [
      "id",
      "type",
      "occurred_at",
      "environment",
      "company_id",
      "subject",
      "references",
      "data",
      "test"
    ],
    "title": "WebhookEnvelope",
    "type": "object"
  }
  ```
</details>

## 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

```json theme={null}
{
  "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
}
```

<details>
  <summary>Complete JSON Schema</summary>

  ```json theme={null}
  {
    "$defs": {
      "References": {
        "additionalProperties": false,
        "properties": {
          "customer_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your customer reference, or null.",
            "title": "Customer Reference"
          },
          "loan_reference": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your exact associated loan reference, or null. Never inferred from another loan.",
            "title": "Loan Reference"
          }
        },
        "required": [
          "customer_reference",
          "loan_reference"
        ],
        "title": "References",
        "type": "object"
      },
      "Subject": {
        "additionalProperties": false,
        "properties": {
          "type": {
            "type": "string",
            "const": "webhook"
          },
          "id": {
            "description": "Stable Finosu resource ID. Email dispatch uses an opaque send identity.",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "sequence": {
            "description": "Compare only within the same company and subject; not a global catch-up cursor.",
            "minimum": 1,
            "title": "Sequence",
            "type": "integer"
          }
        },
        "required": [
          "type",
          "id",
          "sequence"
        ],
        "title": "Subject",
        "type": "object"
      }
    },
    "additionalProperties": false,
    "properties": {
      "id": {
        "description": "Event ID shared across endpoint copies; retained on retry.",
        "format": "uuid",
        "title": "Id",
        "type": "string"
      },
      "type": {
        "description": "Event name from this catalog.",
        "title": "Type",
        "type": "string",
        "const": "webhook.test"
      },
      "occurred_at": {
        "description": "Consumer capture time in UTC; not source commit time.",
        "format": "date-time",
        "title": "Occurred At",
        "type": "string"
      },
      "environment": {
        "description": "Finosu environment; validate against your configured environment.",
        "title": "Environment",
        "type": "string"
      },
      "company_id": {
        "description": "Owning company; validate against your configured company.",
        "format": "uuid",
        "title": "Company Id",
        "type": "string"
      },
      "subject": {
        "$ref": "#/$defs/Subject"
      },
      "references": {
        "$ref": "#/$defs/References"
      },
      "data": {
        "additionalProperties": false,
        "properties": {
          "message": {
            "description": "Synthetic setup message containing no borrower data.",
            "title": "Message",
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "title": "WebhookTestData",
        "type": "object"
      },
      "test": {
        "description": "True for a test-customer event or an explicit synthetic endpoint test. Test-customer events follow ordinary subscriptions and do not verify an endpoint.",
        "title": "Test",
        "type": "boolean",
        "const": true
      }
    },
    "required": [
      "id",
      "type",
      "occurred_at",
      "environment",
      "company_id",
      "subject",
      "references",
      "data",
      "test"
    ],
    "title": "WebhookEnvelope",
    "type": "object"
  }
  ```
</details>


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