Skip to main content

​
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:
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.