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 anHTTP 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 awebhook.test payload to that URL. The dashboard reports the result:
- Success — “Webhook delivered successfully.” Your endpoint responded with a
2xxstatus. - Failure — An error toast. Verify the URL is correct, publicly accessible over HTTPS, and returns a
2xxresponse.
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 emptywebhookEvents list means no events, and unknown event names are rejected.
- Only care about final outcomes? Select just
build.approvedandbuild.rejected. - Want full pipeline visibility? Tick all eight events.
- Gating releases from CI? Upload with
autoRelease: falseand act onbuild.ready. - Monitoring distribution? Select
build.distributingandbuild.approved.
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.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:
- Node.js (Express)
- Python (Flask)
Receiving webhooks
- Node.js (Express)
- Python (Flask)
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.