# Webhook Notifications Overview

This guide provides a business-friendly overview of Quantum webhook notifications — what they are, what events you'll receive, and how they map to the loan application lifecycle.

## Table of Contents

- [What Are Webhooks?](#what-are-webhooks)
- [Why Use Webhooks?](#why-use-webhooks)
- [Event Notifications](#event-notifications)
- [Application Lifecycle](#application-lifecycle)
- [Understanding Event Data](#understanding-event-data)
- [Subscription Management](#subscription-management)
- [Glossary](#glossary)

---

## What Are Webhooks?

Webhooks are automatic notifications sent to your systems whenever something important happens with a loan application. Instead of repeatedly checking for updates (polling), Quantum proactively sends you real-time notifications.

**Think of it like this:** Rather than calling to check if your package has shipped, the delivery company sends you a text message the moment it's on its way.

---

## Why Use Webhooks?

| Benefit | Description |
|---------|-------------|
| **Real-time updates** | Know immediately when application status changes, offers are created, or documents are signed |
| **Operational efficiency** | Automate your workflows based on application events |
| **Better customer experience** | Update your customers faster with accurate status information |
| **Reduced manual work** | No need to manually check application statuses |
| **Audit trail** | Complete history of all events for compliance and reporting |

---

## Event Notifications

When you subscribe to webhooks, you choose which events you want to receive. Here's what each event means in business terms:

### Application Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Application Created** | A new loan application has been submitted | Customer completes and submits their application |
| **Application Updated** | Application information has been modified | Customer or system updates application details |
| **Status Updated** | The application has moved to a new stage | Application progresses through the pipeline |

### Offer Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Offer Created** | A loan offer has been generated for the applicant | Underwriting approves the application and generates terms |
| **Offer Selected** | The customer has accepted a loan offer | Customer reviews and accepts the proposed terms |
| **Offer Declined** | The customer has declined the loan offer | Customer chooses not to proceed with the offered terms |

### Document Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Document Uploaded** | A document has been submitted | Customer uploads required documents (bank statements, etc.) |
| **Document Status Updated** | A document has been reviewed | Document is approved, rejected, or requires resubmission |

### Contract Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Contract Sent** | Loan documents have been sent for signature | After offer acceptance, final documents are prepared |
| **Contract Signed** | All parties have signed the loan agreement | Customer completes document signing |

### Task Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Tasks Updated** | Action items for the application have changed | New tasks created or existing tasks completed |

### Prefill Application Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Prefill Application Created** | A prefilled application has been created via the Prefill API | Partner submits a prefill request on behalf of an applicant |
| **Prefill Application Token Expired** | An applicant tried to use an expired prefill link | Applicant clicks a prefill URL after the token has expired |

{% callout type="info" %}
Learn more about the prefill workflow in the [Prefill Applications](/prefill-applications.html) guide.
{% /callout %}

### Other Events

| Event | What It Means | When It Happens |
|-------|---------------|-----------------|
| **Funding Started** | The loan funding process has begun | After all documents are signed and verified |
| **Adverse Action Sent** | An adverse action notice has been sent to the applicant | Adverse action notices are sent for declined applications once a day at 9 pm ET |
| **Additional Owner Profile Completed** | A business co-owner has completed their profile | Multi-owner applications where additional owners submit info |

---

## Application Lifecycle

### The Happy Path: Approved Application

Here's the typical journey of a successful loan application and the notifications you'll receive:

```
1. APPLICATION SUBMITTED
   └─→ Event: Application Created
   └─→ Event: Status Updated → "In Processing"

2. DOCUMENT COLLECTION
   └─→ Event: Tasks Updated (new task: upload bank statements)
   └─→ Event: Document Uploaded (customer submits documents)
   └─→ Event: Document Status Updated (documents approved)
   └─→ Event: Tasks Updated (task completed)

3. CREDIT REVIEW
   └─→ Event: Status Updated → "Under Credit Review"
   └─→ Event: Status Updated → "Approved"

4. OFFER STAGE
   └─→ Event: Offer Created
   └─→ Event: Status Updated → "Awaiting Offer Acceptance"
   └─→ Event: Offer Selected (customer accepts)

5. DOCUMENT PREPARATION
   └─→ Event: Status Updated → "Preparing Loan Documents"
   └─→ Event: Status Updated → "Pending Closing Information"
   └─→ Event: Tasks Updated (additional documents needed)
   └─→ Event: Document Uploaded (customer submits)
   └─→ Event: Document Status Updated (documents approved)
   └─→ Event: Tasks Updated (tasks completed)

6. CONTRACT SIGNING
   └─→ Event: Contract Sent
   └─→ Event: Status Updated → "Awaiting Document Execution"
   └─→ Event: Contract Signed

7. FUNDING
   └─→ Event: Status Updated → "Awaiting Funding"
   └─→ Event: Funding Started
   └─→ Event: Status Updated → "Booked"
```

### When Customer Declines the Offer

```
1-4. Same as happy path through Offer Created...

5. CUSTOMER DECISION
   └─→ Event: Offer Declined (customer declines)
   └─→ Event: Status Updated → "Offer Declined"
```

### When Application Is Declined

```
1-2. Same as happy path through Document Collection...

3. CREDIT REVIEW
   └─→ Event: Status Updated → "Under Credit Review"
   └─→ Event: Status Updated → "Declined"
   └─→ Event: Adverse Action Sent (notice sent in the daily 9 pm ET batch)
```

---

## Application Statuses

| Status | Meaning |
|--------|---------|
| **Submitted** | Application received, initial processing beginning |
| **In Processing** | Application is being prepared for review |
| **Under Credit Review** | Underwriting team is evaluating the application |
| **Approved** | Application approved, offer being prepared |
| **Awaiting Offer Acceptance** | Offer sent, waiting for customer decision |
| **Preparing Loan Documents** | Customer accepted, documents being prepared |
| **Pending Closing Information** | Additional information needed from customer |
| **Awaiting Document Execution** | Loan documents sent for signature |
| **Awaiting Funding** | Documents signed, funding being processed |
| **Booked** | Loan funded and complete |
| **Declined** | Application not approved |
| **Offer Declined** | Customer chose not to accept the offer |
| **Withdrawn** | Application withdrawn by customer or partner |

---

## Understanding Event Data

Each webhook notification includes key information:

| Field | Description | Example |
|-------|-------------|---------|
| **Event ID** | Unique identifier for this event | `f47ac10b-58cc-4372-a567-0e02b2c3d479` |
| **Event Type** | What happened | `application.offer.created` |
| **Resource ID** | Which application this relates to | `88c911f7-1a59-4860-b786-825c9b45bc1b` |
| **Occurred At** | When the event happened | `2025-01-12T20:36:24Z` |
| **Resource URL** | Link to get more details | `https://qa.quantumlends.com/api/v3/applications/...` |

---

## Subscription Management

### What You Can Control

| Setting | Options | Description |
|---------|---------|-------------|
| **Events** | Select specific events | Only receive notifications you care about |
| **Filters** | Per-event conditions | Narrow which notifications you receive based on event data (e.g. only declined status updates) |
| **Status** | Active / Paused / Disabled | Control when you receive notifications |
| **Retries** | 0-6 attempts | How many times we retry if your system is unavailable |

{% callout type="info" %}
Filters let you receive only the events that matter — for example, getting a notification only when an application is declined, instead of for every status change. The initial release supports filtering **status updates** by status value. For configuration details, see [Filtering Events](/webhooks-guide.html#filtering-events) in the integration guide.
{% /callout %}

### Subscription Statuses

| Status | Meaning |
|--------|---------|
| **Active** | Receiving notifications normally |
| **Paused** | Temporarily stopped (useful during maintenance) |
| **Disabled** | Permanently stopped |

### Viewing Delivery History

You can review all webhook deliveries through the API or dashboard:
- See which events were sent
- Check delivery success/failure
- View retry attempts
- Manually retry failed deliveries

---

## Glossary

| Term | Definition |
|------|------------|
| **Webhook** | An automatic HTTP notification sent when an event occurs |
| **Event** | Something that happened (e.g., status change, document upload) |
| **Subscription** | Your configuration for receiving webhooks (URL, events, settings) |
| **Delivery** | An attempt to send an event notification to your system |
| **Payload** | The data included in a webhook notification |
| **Adverse Action** | A decline decision with required regulatory notifications |
| **Underwriting** | The process of evaluating a loan application |

---

## Questions?

For technical implementation details, see the [Webhooks Integration Guide](/webhooks-guide.html).

For assistance with webhook setup or questions about your integration, please contact your Quantum partner representative.