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

# Webhook Event Reference

> Reference the Starfire AI webhook event families for runs, builds, research, artifacts, files, billing, and usage threshold notifications.

# Webhook event reference

Webhook events notify your backend that something changed asynchronously in Starfire.

The exact event catalog is defined by the active Developer Platform contract. The Alpha architecture includes event families such as the following.

## Run events

```text theme={null}
run.created
run.started
run.completed
run.failed
run.cancelled
```

## Build events

```text theme={null}
build.created
build.started
build.completed
build.failed
build.cancelled
```

## Research events

```text theme={null}
research.created
research.completed
research.failed
```

## File and artifact events

```text theme={null}
file.processed
file.failed
artifact.created
artifact.deleted
artifact.expiring
```

## Billing and usage events

Where enabled for developer applications:

```text theme={null}
subscription.changed
usage.threshold
```

## Event envelope

A useful event contains concepts such as:

* event ID
* event type
* created time
* owning application/organization context
* resource ID
* payload version
* resource snapshot or relevant change metadata

Use the active OpenAPI/webhook reference for the exact payload.

## Idempotency

The same logical event can be delivered more than once. Store the event ID and make your consumer safe to run repeatedly.

## Ordering

Do not assume every event for every resource arrives globally in perfect order unless the contract explicitly guarantees it. Compare resource state when ordering matters.

## Verification

Verify the documented webhook signature mechanism before trusting the payload.

<Warning>
  A `completed` event indicates Starfire's workflow reached its completed state. Your own downstream processing can still fail and should have independent observability/retry behavior.
</Warning>