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

# Webhooks

> Receive asynchronous Starfire AI events, understand delivery attempts, retries, event identifiers, and webhook ownership.

# Webhooks

Webhooks let Starfire notify your backend when an asynchronous event occurs without requiring your application to poll continuously.

They are especially useful for long-running work such as research or FORGE builds.

## Webhook endpoint

A webhook configuration associates an application or developer context with an HTTPS endpoint and a selected set of event types.

Conceptual event families include:

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

build.created
build.completed
build.failed

artifact.created
artifact.deleted

file.processed
file.failed

research.completed
subscription.changed
usage.threshold
```

The exact event catalog is defined by the active Developer Platform contract.

## Delivery record

Starfire's developer architecture is designed to keep delivery metadata such as:

* event type
* event identifier
* destination
* attempt number
* response status
* latency
* timestamp
* next retry when applicable

This lets developers distinguish “event never occurred” from “event occurred but delivery failed.”

## Retries

Temporary delivery failures can be retried using a backoff policy. Integrations should assume that the same event can be delivered more than once.

Use the event identifier to make your webhook consumer idempotent.

## Verification

When webhook-signing support is enabled, verify the documented signature mechanism before trusting the payload as a Starfire event.

<Warning>
  Do not put your webhook verification secret into frontend code or public documentation. Store it with your backend integration credentials.
</Warning>

## Respond quickly

A webhook receiver should acknowledge valid deliveries quickly and move expensive processing into its own background work. Holding the connection open for a long internal job increases the chance of timeout and duplicate delivery.

## Replay and manual retry

The Developer Platform design includes delivery history and manual retry concepts so a failed downstream service does not require recreating the original Starfire run.

## Organization ownership

For business integrations, associate webhook endpoints with an organization-owned application where possible. That keeps delivery configuration independent from one employee's personal account.

<Card title="Applications & service accounts" icon="server" href="/developers/applications-service-accounts">
  Organize keys, webhooks, usage, and permissions around a durable application identity.
</Card>