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:

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.

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

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.

Applications & service accounts

Organize keys, webhooks, usage, and permissions around a durable application identity.