Webhook event reference

This page is the canonical reference for every webhook event Streampixel sends. For setup (where to enter your URL, how to choose events, retry behavior, handler best practices), see the main Webhooks page.

Quick links

Webhook setup

Configure your URL, choose events, and follow handler best practices.

Upload File API

The endpoint that kicks off the build pipeline and the events below.

Pipeline overview

Every uploaded build moves through a fixed sequence of pipeline stages. Each stage transition fires a webhook event (subject to your subscription filters). A build uploaded with autoRelease: true goes straight from saving to distribution. With autoRelease: false it stops at Ready and fires build.ready; nothing more happens until you activate it (Set Active Build or Distribute File), which then produces build.distributing and build.approved. The dashed edges show where a build can fail instead: a download that fails after every retry, an archive that fails extraction or validation, or a copy to the streaming servers that fails. Every one of these fires build.rejected, with status naming the stage (Download Failed or Reject) and objection explaining why. Once rejected, no further events fire for that build.

Common payload fields

Every webhook payload (build events and the test event) shares the same envelope.

Field	Type	Description
`event`	`string`	The event name (e.g., `build.approved`).
`eventId`	`string`	Unique per delivery (UUID). Use it as your idempotency key: the same transition can be delivered twice when a build server retries. Also sent as the `X-Streampixel-Event-Id` header.
`projectId`	`string`	The Streampixel project the event belongs to.
`uploadId`	`string \| null`	The build identifier. `null` for events that fire before an upload exists.
`fileUrl`	`string \| null`	The build’s source URL. May be `null` for early-pipeline events.
`status`	`string`	Raw pipeline status string for the build.
`objection`	`string \| null`	Reason for rejection. Only populated on `build.rejected`.
`redistribution`	`boolean`	`true` when the pipeline re-copied a build that is already live (a restore, a new streaming server, a retry). The build did not change, so a “deploy on `build.approved`” listener should ignore deliveries with this flag.
`timestamp`	`string`	ISO 8601 timestamp of when the event occurred.

All deliveries are HTTP POST with Content-Type: application/json and a 10-second timeout. There are no retries — see the Webhooks page for handler best practices.

Events

`build.uploaded`

Triggered by: A new build has been accepted by POST /projects/upload-file and queued for processing. This is the very first event in the pipeline. Status at trigger: pending.

{
  "event": "build.uploaded",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": null,
  "status": "pending",
  "objection": null,
  "timestamp": "2026-03-29T13:00:00.000Z"
}

Notes: fileUrl may be null at this stage because the upload manager has not yet resolved the source. Use uploadId as your correlation key going forward.

`build.downloading`

Triggered by: The build manager has begun downloading the .zip from the URL you submitted. Status at trigger: Downloading Files.

{
  "event": "build.downloading",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://your-bucket.s3.amazonaws.com/builds/v1.2.0.zip",
  "status": "Downloading Files",
  "objection": null,
  "timestamp": "2026-03-29T13:00:12.000Z"
}

Notes: A long-running build.downloading without progressing to build.extracting usually means the source URL is slow or unreachable.

`build.extracting`

Triggered by: The downloaded archive is being extracted and scanned for required files. Status at trigger: Extracting & Scanning.

{
  "event": "build.extracting",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://your-bucket.s3.amazonaws.com/builds/v1.2.0.zip",
  "status": "Extracting & Scanning",
  "objection": null,
  "timestamp": "2026-03-29T13:01:30.000Z"
}

Notes: If the archive is malformed or missing the expected Unreal binary, the build skips to build.rejected with an objection describing the failure.

`build.saving`

Triggered by: The validated build is being persisted to the project repository. Status at trigger: Saving to Repository.

{
  "event": "build.saving",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://your-bucket.s3.amazonaws.com/builds/v1.2.0.zip",
  "status": "Saving to Repository",
  "objection": null,
  "timestamp": "2026-03-29T13:03:00.000Z"
}

Notes: This stage is typically short. After build.saving, a build uploaded with autoRelease: true moves straight on to build.distributing; with autoRelease: false it stops and fires build.ready instead.

`build.distributing`

Triggered by: The build is being copied to streaming servers and made ready to serve traffic. Fires when autoRelease was true on upload, or when Distribute File API was called manually. Status at trigger: Distributing to Servers (or Distribute when triggered from the dashboard’s Set Live button).

{
  "event": "build.distributing",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://your-bucket.s3.amazonaws.com/builds/v1.2.0.zip",
  "status": "Distributing to Servers",
  "objection": null,
  "timestamp": "2026-03-29T13:05:00.000Z"
}

Notes: Subscribe to this event if you want to know when streaming servers are warming up — the build is almost ready, but not yet live.

`build.ready`

Triggered by: The build was processed successfully but not distributed, because it was uploaded with autoRelease: false. It is waiting for you to activate it. Status at trigger: Ready.

{
  "event": "build.ready",
  "eventId": "6d1f3c5e-2b4a-4c6e-9d8f-0a1b2c3d4e5f",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://your-bucket.s3.amazonaws.com/builds/v1.2.0.zip",
  "status": "Ready",
  "objection": null,
  "redistribution": false,
  "timestamp": "2026-03-29T13:04:30.000Z"
}

Notes: This is the event to wait for in a gated CI/CD flow: on build.ready, run your checks, then call Set Active Build or Distribute File. build.distributing and build.approved follow once you do.

`build.approved`

Triggered by: Distribution finished successfully and the build is now the live build for the project. This is the event most CI/CD pipelines key off of. Status at trigger: Approved.

{
  "event": "build.approved",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://your-bucket.s3.amazonaws.com/builds/v1.2.0.zip",
  "status": "Approved",
  "objection": null,
  "timestamp": "2026-03-29T13:08:00.000Z"
}

Notes: Treat this as the “go-live” signal — kick off downstream deploys, smoke tests, or release announcements here.

`build.rejected`

Triggered by: The build failed at any stage of the pipeline: the download gave up after every retry, the archive failed extraction or validation, or the copy to the streaming servers failed. Once rejected, no further events fire for this uploadId. Status at trigger: Reject, or Download Failed when the source could not be fetched (an expired or unreachable URL). objection carries the reason in both cases.

{
  "event": "build.rejected",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://your-bucket.s3.amazonaws.com/builds/v1.2.0.zip",
  "status": "Reject",
  "objection": "Build contains unsupported file formats.",
  "timestamp": "2026-03-29T13:04:30.000Z"
}

Notes: Always read objection to learn why the build was rejected. Surface it in your team’s CI logs or chat so the developer who pushed the build can act on it.

`webhook.test`

Triggered by: Manually clicking the Test button in Project Settings. Never fired during real build operations. Status at trigger: test.

{
  "event": "webhook.test",
  "projectId": "test_project_id",
  "uploadId": "test_upload_id",
  "fileUrl": "https://example.com/test-build.zip",
  "status": "test",
  "objection": null,
  "timestamp": "2026-03-29T14:30:00.000Z"
}

Notes: All ID fields are placeholder strings — they do not correspond to real records. Your handler should detect this event and short-circuit any state-machine logic that would otherwise act on it.

Event timing summary

Event	Fires when	Typical delay from upload
`build.uploaded`	API accepts the upload	Immediate
`build.downloading`	Download begins	Seconds
`build.extracting`	Extraction begins	Tens of seconds
`build.saving`	Persist begins	A minute or two
`build.ready`	Processing finished, `autoRelease: false`	A minute or two after `saving`
`build.distributing`	Distribution begins	A minute or two after `saving` (`autoRelease: true`), or when you activate
`build.approved`	Build is live	Variable — depends on build size
`build.rejected`	Download, validation or distribution fails	Any time during the pipeline
`webhook.test`	Manual or API trigger	Immediate

Times above are typical, not guaranteed. Larger builds, busy regions, and slow source URLs can all extend pipeline duration significantly.

Handling events safely

A few rules that apply across every event:

Use uploadId + event as your idempotency key. In rare cases the same event may arrive more than once; deduplicate on your side.
Acknowledge fast. Return 200 OK within 10 seconds, then process in the background. Streampixel does not retry failed deliveries — see the Webhooks page for full guidance.
Tolerate unknown events. New events may be added in the future; your handler should treat unfamiliar event strings as a no-op rather than crashing.
Validate the project. Confirm projectId matches a project you expect — never act on a webhook for an unknown project.

Getting started

Projects

Builds

Project control

Sessions & analytics

Webhooks

Integrations

Webhook event reference

Quick links

Webhook setup

Upload File API

Pipeline overview

Common payload fields

Events

`build.uploaded`

`build.downloading`

`build.extracting`

`build.saving`

`build.distributing`

`build.ready`

`build.approved`

`build.rejected`

`webhook.test`

Event timing summary

Handling events safely

Next steps

Webhook setup

Upload File API

​Quick links

Webhook setup

Upload File API

​Pipeline overview

​Common payload fields

​Events

​build.uploaded

​build.downloading

​build.extracting

​build.saving

​build.distributing

​build.ready

​build.approved

​build.rejected

​webhook.test

​Event timing summary

​Handling events safely

​Next steps

Webhook setup

Upload File API

Quick links

Pipeline overview

Common payload fields

Events

`build.uploaded`

`build.downloading`

`build.extracting`

`build.saving`

`build.distributing`

`build.ready`

`build.approved`

`build.rejected`

`webhook.test`

Event timing summary

Handling events safely

Next steps