Overview

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

Open project settings

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

Enter your webhook URL

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

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.

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.

Event	Description
`build.uploaded`	A new build file has been uploaded to the project.
`build.downloading`	The build file is being downloaded for processing.
`build.extracting`	The build file is being extracted and scanned.
`build.saving`	The build is being saved to the repository.
`build.distributing`	The build is being distributed to streaming servers.
`build.approved`	The build has been reviewed and approved.
`build.rejected`	The build has been reviewed and rejected.

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

{
  "event": "build.approved",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://cdn.streampixel.io/builds/my-build.zip",
  "status": "Approved",
  "objection": null,
  "timestamp": "2026-03-29T14:30:00.000Z"
}

{
  "event": "build.rejected",
  "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
  "uploadId": "665a2b3c4d5e6f7a8b9c0e1f",
  "fileUrl": "https://cdn.streampixel.io/builds/my-build.zip",
  "status": "Reject",
  "objection": "Build contains unsupported file formats.",
  "timestamp": "2026-03-29T15:00:00.000Z"
}

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

{
  "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"
}

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. At least one event must be selected while a webhook URL is set — there is no “all” default, so a new webhook receives nothing until you tick the events you want:

Only care about final outcomes? Select just build.approved and build.rejected.
Want full pipeline visibility? Tick all seven events.
Monitoring distribution? Select build.distributing and build.approved.

If an event occurs that you have not subscribed to, no request is sent.

Best practices

Streampixel does not retry failed webhook deliveries. If your endpoint is unreachable or returns a non-2xx status, the event is lost. Make sure your endpoint has high availability.

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.
Be idempotent — in rare cases the same event may arrive more than once. Use uploadId + event as an idempotency key.
Log everything — log all incoming payloads. Logs are invaluable for debugging integration issues.
Validate the project — confirm projectId matches the project you expect.
Monitor uptime — there are no retries, so any downtime means missed events. Set up uptime monitoring for your endpoint.

Receiving webhooks

Node.js (Express)
Python (Flask)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/streampixel', (req, res) => {
  const { event, projectId, uploadId, objection } = req.body;

  console.log(`Received event: ${event} for project: ${projectId}`);

  switch (event) {
    case 'build.approved':
      console.log(`Build ${uploadId} approved. Triggering deployment...`);
      // Start your deployment pipeline
      break;

    case 'build.rejected':
      console.log(`Build ${uploadId} rejected. Reason: ${objection}`);
      // Notify your team
      break;

    case 'webhook.test':
      console.log('Test webhook received successfully!');
      break;

    default:
      console.log(`Event: ${event}`);
  }

  // Always respond with 200 quickly
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/streampixel', methods=['POST'])
def handle_webhook():
    payload = request.get_json()

    event = payload.get('event')
    project_id = payload.get('projectId')
    upload_id = payload.get('uploadId')
    objection = payload.get('objection')

    print(f"Received event: {event} for project: {project_id}")

    if event == 'build.approved':
        print(f"Build {upload_id} approved. Triggering deployment...")
        # Start your deployment pipeline

    elif event == 'build.rejected':
        print(f"Build {upload_id} rejected. Reason: {objection}")
        # Notify your team

    elif event == 'webhook.test':
        print("Test webhook received successfully!")

    # Always respond with 200 quickly
    return jsonify({"received": True}), 200

if __name__ == '__main__':
    app.run(port=3000)

Troubleshooting

Problem	Solution
Test webhook fails	Ensure your URL is publicly accessible (not `localhost`). For local development, use a tool like ngrok.
Not receiving webhooks	Verify the correct events are checked in Project Settings and that your webhook URL is saved.
Receiving timeouts	Your endpoint must respond within 10 seconds. Move heavy work to a background job.
Missing events	Streampixel does not retry failed deliveries. If your server was down when the event fired, the notification is lost. Check your server logs.
Unexpected payload format	Ensure your server parses the `Content-Type: application/json` body correctly.
Duplicate events	Use `uploadId` + `event` as an idempotency key to skip duplicates.

Quick reference

Detail	Value
HTTP method	`POST`
Content type	`application/json`
Timeout	10 seconds
Retries	None
Events available	7 build pipeline events + 1 test event

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.

Getting started

Endpoints

Webhooks

Set up a webhook

Events

Payload

Examples

Testing your endpoint

Filtering events

Best practices

Receiving webhooks

Troubleshooting

Quick reference

Next steps

Distribute a build

Upload File API

​Set up a webhook

​Events

​Payload

​Examples

​Testing your endpoint

​Filtering events

​Best practices

​Receiving webhooks

​Troubleshooting

​Quick reference

​Next steps

Distribute a build

Upload File API

Set up a webhook

Events

Payload

Examples

Testing your endpoint

Filtering events

Best practices

Receiving webhooks

Troubleshooting

Quick reference

Next steps