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

run.created
run.started
run.completed
run.failed
run.cancelled

Build events

build.created
build.started
build.completed
build.failed
build.cancelled

Research events

research.created
research.completed
research.failed

File and artifact events

file.processed
file.failed
artifact.created
artifact.deleted
artifact.expiring

Billing and usage events

Where enabled for developer applications:

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.

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.