Webhooks

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

Common use cases:

• Trigger deployments when a build is approved

• Send Slack or Discord alerts when a build is rejected

• Track build pipeline activity in your own monitoring systems

• Kick off automated testing

Setting Up Webhooks

1. Open your project in the Streampixel dashboard.

2. Go to Project Settings.

3. Enter your publicly accessible HTTPS endpoint in the Webhook URL field.

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

5. Click Save.

6. Click the Test button to verify your endpoint is working.

Your endpoint must be reachable from the internet and able to accept HTTP POST requests.

Webhook Events

Streampixel sends webhooks 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 the order listed above, following the natural progression of the build pipeline. Not every build will trigger every event — for example, a rejected build will not fire build.distributing.

Payload Reference

Every webhook is an HTTP POST request with a JSON body and Content-Type: application/json header.

Fields

Field	Type	Description
event	string	The event type (e.g., build.approved). See the events table above.
projectId	string	The unique identifier of your Streampixel project.
uploadId	string or null	The unique identifier of the uploaded build file.
fileUrl	string or null	The URL of the build file, if available.
status	string	The raw pipeline status (e.g., Approved, Reject, Distribute).
objection	string or null	The reason for rejection. Only populated when event is build.rejected.
timestamp	string	ISO 8601 timestamp of when the event occurred.

Example: Build Approved

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

Example: Build Rejected

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

Example: Build Uploaded

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

Testing Your Webhook

Click the Test button in Project Settings to send a test payload to your configured URL. The test payload looks like this:

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

• Success — The dashboard confirms the test was sent. Your endpoint responded with a 2xx status code.

• Failure — The dashboard shows an error. Check that your 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.

Event Filtering

By default, all seven build events are enabled. You can customize which events you receive using the checkboxes in Project Settings.

Examples:

• Only care about final outcomes? Select just build.approved and build.rejected.

• Want full pipeline visibility? Keep all events selected.

• Monitoring distribution? Select build.distributing and build.approved.

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

Best Practices

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

• Respond quickly — Return a 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 to ensure the payload is encrypted in transit.

• Be idempotent — In rare cases the same event may arrive more than once. Use the uploadId + event combination to detect and skip duplicates.

• Log everything — Log all incoming payloads for debugging. This makes it much easier to troubleshoot integration issues.

• Validate the project — Check that the projectId in the payload matches your expected project.

• Monitor uptime — Since there are no retries, any downtime means missed events. Set up uptime monitoring for your webhook endpoint.

Example: Receiving Webhooks

Node.js (Express)

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');
});

Python (Flask)

Troubleshooting

Problem	Solution
Test webhook fails	Ensure your URL is publicly accessible (not localhost). Use a tool like ngrok for local development.
Not receiving webhooks	Verify that 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 processing 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 the uploadId + event combination 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