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

# Events Overview

> Understand Spark360 outbound events, trigger points, and availability.

Spark360 publishes lead and widget events from application-layer trigger points after core data writes complete.

| Event            | `leadStatus`                                                  | S360 Outbound Event      | Trigger                              | Availability          |
| ---------------- | ------------------------------------------------------------- | ------------------------ | ------------------------------------ | --------------------- |
| `lead.created`   | `address_info_provided`                                       | `lead.address_preview`   | Leads INSERT                         | Optional              |
| `lead.updated`   | `project_details_provided`                                    | *(no outbound event)*    | —                                    | —                     |
| `lead.updated`   | `personal_info_and_estimate_provided`                         | `lead.enriched`          | Enrichment write-back complete       | **REQUIRED — locked** |
| `lead.updated`   | `personal_info_and_estimate_provided` + `ownerOccupied=false` | `lead.rental_alert`      | Same as above, occupancy check       | Optional              |
| `lead.updated`   | `contact_info_provided`                                       | `lead.contact_requested` | Leads UPDATE                         | Optional              |
| `widget.updated` | n/a                                                           | `widget.status_changed`  | `organizations.widget_status` UPDATE | Optional              |

<Note>
  `lead.enriched` is mandatory for every webhook subscription and cannot be deselected.
</Note>

## Source tracking — captured per-widget

Every lead event includes a `source_tracking` block reflecting the specific widget and source that captured the lead. For multi-widget organizations (Ultimate and Premium tiers), the values identify which specific widget produced the lead:

```json theme={null}
{
  "source_tracking": {
    "widget_version": "02",
    "widget_name": "New Spark 02",
    "source_code": "03",
    "source_label": "Instagram"
  }
}
```

For single-widget organizations (Starter tier), the values default to the Primary widget and the originating source:

```json theme={null}
{
  "source_tracking": {
    "widget_version": "01",
    "widget_name": "Primary",
    "source_code": "01",
    "source_label": "Website"
  }
}
```

## Event sequencing notes

1. `lead.address_preview` fires first on initial address submission and is address-only (no name or contact info).
2. `lead.enriched` fires after enrichment is complete and write-back includes scores, buyer insights, and roof estimate fields.
3. `lead.rental_alert` can fire alongside `lead.enriched` when `owner_occupied = false`.
4. `lead.contact_requested` fires last only if the homeowner completes the optional contact preference step.

<Note>
  `lead.contact_requested` is optional and only fires when the final contact step is completed. It always arrives after `lead.enriched`, never before.
</Note>