Skip to main content
Webhooks push HTTP notifications to your endpoint whenever a build event happens — uploaded, approved, rejected, distributed. Use them to trigger deploys, post alerts, kick off tests, or mirror pipeline state into your monitoring stack.

Set up a webhook

1

Open project settings

From the dashboard, navigate to your project and open Project Settings.
2

Enter your webhook URL

Provide a publicly accessible HTTPS endpoint in the Webhook URL field.
3

Choose events

Tick the checkboxes for the build events you want to receive. At least one event must be selected while a webhook URL is set.
4

Save and test

Click Save. Once saved, click Test Webhook to send a sample payload to your endpoint. (Save first — the Test button won’t fire on unsaved changes.)
Your endpoint must be reachable from the internet and able to accept HTTP POST requests with a JSON body.

Events

Streampixel emits a webhook at each stage of the build pipeline. Events fire in roughly the order listed, following the natural progression of the pipeline. Not every build triggers every event — for example, a rejected build never fires build.distributing.

Payload

Every webhook is an HTTP POST request with Content-Type: application/json.
string
The event type (e.g., build.approved). See the events table above.
string
The Streampixel project ID.
string | null
The unique identifier of the uploaded build.
string | null
The URL of the build file, when available.
string
Raw pipeline status (e.g., Approved, Reject, Distribute).
string | null
The reason for rejection. Only populated when event is build.rejected.
string
ISO 8601 timestamp of when the event occurred.

Examples

Testing your endpoint

Save a webhook URL in Project Settings, then click the Test Webhook button to send a webhook.test payload to that URL. The dashboard reports the result:
  • Success — “Webhook delivered successfully.” Your endpoint responded with a 2xx status.
  • Failure — An error toast. Verify the URL is correct, publicly accessible over HTTPS, and returns a 2xx response.
The webhook.test event is only sent when you click the Test Webhook button. It is never fired during normal build operations.

Filtering events

Choose exactly the events you care about with the checkboxes in Project Settings. A new project is subscribed to every build event; the dashboard requires at least one event to stay ticked while a webhook URL is set. Through the Update Project Settings API an empty webhookEvents list means no events, and unknown event names are rejected.
  • Only care about final outcomes? Select just build.approved and build.rejected.
  • Want full pipeline visibility? Tick all eight events.
  • Gating releases from CI? Upload with autoRelease: false and act on build.ready.
  • Monitoring distribution? Select build.distributing and build.approved.
If an event occurs that you have not subscribed to, no request is sent.

Best practices

Retries. A delivery that fails — a network error, a timeout, a 408, 429 or any 5xx — is retried after 1 min, 5 min, 30 min, 2 h, 6 h and 24 h (7 attempts over about 33 hours), then marked dead. Any other 4xx and any redirect is treated as a permanent answer and is not retried. Every attempt is recorded in the delivery log under Project Settings → Webhooks for 30 days, where any delivery can be sent again with Resend.
  • Respond quickly — return 200 OK as fast as possible. Streampixel waits up to 10 seconds before timing out. Move heavy processing to a background job.
  • Use HTTPS — always use an HTTPS URL so payloads are encrypted in transit.
  • Verify the signature — check X-Streampixel-Signature before acting on an event (see below).
  • Be idempotent — retries and manual resends deliver the same event again with the same eventId. Skip an eventId you have already processed.
  • Log everything — log all incoming payloads. Logs are invaluable for debugging integration issues.
  • Validate the project — confirm projectId matches the project you expect.
  • Check the delivery log — when something seems missing, Project Settings → Webhooks shows every attempt, the response code and the next retry time.

Signature and headers

Every delivery carries three headers: The signing secret is created when you save a webhook URL and is shown under Project Settings → Webhooks → Signing secret (account owner and admins only; it can be rotated there). Verify the signature with the raw body bytes, before parsing JSON, and reject timestamps older than a few minutes to stop replays:

Receiving webhooks

Troubleshooting

Quick reference

Next steps

Distribute a build

Combine build.approved events with the Distribute API for a controlled CI/CD flow.

Upload File API

The endpoint that triggers the build pipeline events documented above.