Webhooks

Webhooks let your application receive real-time HTTP notifications when events happen in your Streampixel project — a build being uploaded, approved, rejected, distributed, and so on. Instead of polling for updates, Streampixel pushes event data directly to your endpoint.

Common use cases

Trigger deployments

Run release jobs as soon as a build is approved.

Send team alerts

Post to Slack or Discord when a build is rejected.

Track pipeline activity

Mirror build events into your monitoring stack.

Automated testing

Kick off smoke tests on every approved build.

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

Use the event checkboxes to select which events you want (all are selected by default).

Save and test

Click Save, then Test to send a test payload to your endpoint.

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.

event

string

The event type (e.g., build.approved). See the events table above.

projectId

string

The Streampixel project ID.

uploadId

string | null

The unique identifier of the uploaded build.

fileUrl

string | null

The URL of the build file, when available.

status

string

Raw pipeline status (e.g., Approved, Reject, Distribute).

objection

string | null

The reason for rejection. Only populated when event is build.rejected.

timestamp

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

Testing your endpoint

Click the Test button in Project Settings to send a webhook.test payload to your configured URL.

Success — The dashboard confirms the test was sent. Your endpoint responded with a 2xx status.
Failure — The dashboard shows an error. Verify the URL is correct, publicly accessible, and returns a 2xx response.

The webhook.test event is only sent when you click the Test button. It is never fired during normal build operations.

Filtering events

By default, all seven build events are enabled. Customize which events you receive using the checkboxes in Project Settings:

Only care about final outcomes? Select just build.approved and build.rejected.
Want full pipeline visibility? Keep all events enabled.
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

Common use cases

Trigger deployments

Send team alerts

Track pipeline activity

Automated testing

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

Getting started

Endpoints

Webhooks

Documentation Index

​Common use cases

Trigger deployments

Send team alerts

Track pipeline activity

Automated testing

​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

Common use cases

Set up a webhook

Events

Payload

Examples

Testing your endpoint

Filtering events

Best practices

Receiving webhooks

Troubleshooting

Quick reference

Next steps