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

# Webhooks

> Receive real-time notifications for underwriting application status changes, decisions, and information requests.

Webhooks allow your system to receive real-time notifications when underwriting applications change state or when underwriting actions occur. Using webhooks is the recommended way to monitor application progress asynchronously without polling the API.

Underwriting-related webhooks are emitted for key lifecycle events, including application status changes, information requests, and final decisions.

<Warning>
  Webhooks are the preferred method for tracking application progress. They provide real-time
  notifications, reduce API load, and enable responsive integrations that can react immediately to
  underwriting events.
</Warning>

## Supported webhook events

Tesouro emits webhooks for the following underwriting events:

### Application status events

These events track the application as it progresses through the underwriting lifecycle:

* **Application submitted** – The application has been submitted for underwriting review
* **Application entered Processing** – Automated checks and verifications have begun
* **Application entered Pending** – Manual underwriting review is required
* **Application reached a final decision:**
  * Approved
  * Declined
  * Withdrawn

<Callout icon="clapperboard-play" color="#6938EF" type="scenario">
  **Scenario**

  Ben configures webhooks to receive notifications when his keyboard business
  application reaches a final decision. When the application is approved, the
  webhook triggers an automated email welcoming him and providing next steps for
  account activation.
</Callout>

### Information request events

These events track when underwriters need additional information:

* **Information request created** – Underwriter has requested additional information (status: REQUESTED)
* **Information request fulfilled** – The requested information has been provided (status: FULFILLED)

These events allow your system to react to underwriting progress and take appropriate actions, such as notifying users or updating internal workflows.

<Callout icon="clapperboard-play" color="#6938EF" type="scenario">
  **Scenario**

  When an information request is created for Ben's application, a webhook
  notification triggers an automated email to Ben with instructions on what
  documents to upload. When Ben fulfills the request, another webhook confirms
  receipt and notifies the underwriting team.
</Callout>

## Webhook payload structure

Every webhook follows a consistent top-level structure:

### Top-level fields

| Field          | Type   | Description                                        |
| :------------- | :----- | :------------------------------------------------- |
| `version`      | String | Schema version (currently `"1"`)                   |
| `eventType`    | String | The type of business event being delivered         |
| `attemptCount` | String | Number of delivery attempts made (starts at `"1"`) |
| `attributes`   | Object | Nested object containing event-specific data       |

### Common attribute fields

All events include these fields inside the `attributes` object:

| Field              | Type     | Description                                |
| :----------------- | :------- | :----------------------------------------- |
| `eventType`        | String   | Event type (same as top-level `eventType`) |
| `organizationId`   | GUID     | Your organization identifier               |
| `updatedTimestamp` | ISO 8601 | Timestamp when the business event occurred |

Optional actor information is included when an event is triggered by a specific entity:

| Field       | Type   | Possible values               | Description               |
| :---------- | :----- | :---------------------------- | :------------------------ |
| `actorType` | String | `"USER"`, `"APP"`, `"SYSTEM"` | Who triggered the event   |
| `actorName` | String |                               | Display name of the actor |

```json Payload Structure lines theme={null}
{
  "version": "1",
  "eventType": "ACCEPTOR_APPLICATION_SUBMITTED",
  "attemptCount": "1",
  "attributes": { ... }
}
```