Webhooks

Overview

Webhooks allow your systems to receive HTTP POST notifications when events happen in preroll.io. Configure webhook endpoints in Settings → Developer → Webhooks.

Events

Payload Format

All webhook payloads are JSON with the following structure:

{
  "id": "wh_evt_abc123",
  "event": "episode.stage_changed",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "episode_id": "uuid",
    "show_id": "uuid",
    "title": "Episode 42",
    "previous_stage": "Editing",
    "current_stage": "Review"
  }
}

Request Headers

Every webhook request includes the following headers:

Signature Verification

To verify that a webhook request is authentic:

1. Extract the X-PreRoll-Timestamp header value
2. Concatenate: {timestamp}.{raw_request_body}
3. Compute an HMAC-SHA256 using your endpoint's signing secret
4. Compare the hex digest to the value in X-PreRoll-Signature (after removing the sha256= prefix)

Node.js Example

import crypto from "crypto";

function verifyWebhook(req, secret) {
  const timestamp = req.headers["x-preroll-timestamp"];
  const signature = req.headers["x-preroll-signature"];
  const body = req.body; // raw string body

  const payload = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  const received = signature.replace("sha256=", "");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

Python Example

import hmac
import hashlib

def verify_webhook(timestamp: str, body: str, signature: str, secret: str) -> bool:
    payload = f"{timestamp}.{body}"
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    received = signature.replace("sha256=", "")

    return hmac.compare_digest(expected, received)

n8n Setup

To receive preroll.io webhooks in n8n:

1. Create a new workflow with a Webhook trigger node
2. Set the HTTP method to POST and copy the webhook URL
3. In preroll.io, go to Settings → Developer → Webhooks and create a new endpoint with the n8n webhook URL
4. Select which events you want to receive and save — the signing secret will be displayed once

Retry Behavior

Webhook delivery is fire-and-forget:

• Requests have a 10-second timeout
• There are no automatic retries on failure
• Failed deliveries are logged and visible in the delivery log

You can inspect delivery history via the API or in Settings → Developer → Webhooks by selecting an endpoint and viewing its delivery log.