The Platform API

Webhooks

Manage your videos, ask questions, and build applications with the Platform API. Explore the operations below for request details, responses, and examples.

Webhooks

Register HTTP endpoints to receive real-time event notifications. Webhook payloads are signed with HMAC-SHA256 using a per-webhook secret.

GET/api/v1/projects/:projectId/webhooksList webhooks

List webhooks

Returns all registered webhooks for the project. Secrets are masked in the response.

GET/api/v1/projects/:projectId/webhooks/deliveriesGet webhook delivery history

Get webhook delivery history

Returns recent delivery attempts with status codes and response times.

{
  "data": [
    {
      "id": "wh_abc123",
      "name": "Moderation Alerts",
      "url": "https://your-server.com/webhook",
      "events": ["content.flagged", "content.banned", "content.approved"],
      "secret": "whsec_...a1b2",
      "status": "active",
      "createdAt": "2026-02-20T...",
      "stats": {
        "totalCalls": 42,
        "lastTriggered": "2026-02-23T...",
        "successRate": 100,
        "lastStatus": 200
      }
    }
  ],
  "meta": { "total": 1 }
}

POST/api/v1/projects/:projectId/webhooksCreate webhook

Create webhook

The secret is auto-generated and returned only on creation. Store it securely.

{
  "name": "Moderation Alerts",
  "url": "https://your-server.com/webhook",
  "events": ["content.flagged", "content.banned"]
}

Available events: content.flagged, content.approved, content.banned, test

PUT/api/v1/projects/:projectId/webhooks/:webhookIdUpdate webhook

Update webhook

{
  "name": "Updated Name",
  "url": "https://new-endpoint.com/hook",
  "events": ["content.flagged"],
  "status": "paused"
}

DELETE/api/v1/projects/:projectId/webhooks/:webhookIdDelete webhook

Delete webhook

Returns 204 No Content on success.

POST/api/v1/projects/:projectId/webhooks/:webhookId/testSend test delivery

Send test delivery

Sends a test payload to the webhook URL and returns the delivery result.

// Response
{
  "success": true,
  "statusCode": 200,
  "message": "Test webhook delivered successfully"
}

Webhook payload format:

{
  "event": "content.flagged",
  "timestamp": "2026-02-23T10:30:00Z",
  "projectId": "PROJECT_ID",
  "webhookId": "wh_abc123",
  "data": {
    "contentId": "VIDEO_ID",
    "decision": "flag",
    "confidence": 85,
    "flags": [
      { "category": "violence", "severity": "medium", "confidence": 0.85 }
    ]
  }
}

Signature verification:

import hmac, hashlib

def verify_webhook(payload_bytes, signature_header, secret):
    """Verify webhook signature from X-Webhook-Signature header."""
    expected = hmac.new(
        secret.encode(), payload_bytes, hashlib.sha256
    ).hexdigest()
    received = signature_header.replace("sha256=", "")
    return hmac.compare_digest(expected, received)

# In your webhook handler:
# signature = request.headers["X-Webhook-Signature"]
# verify_webhook(request.body, signature, "whsec_your_secret")

const crypto = require("crypto");

function verifyWebhook(body, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const received = signatureHeader.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(received)
  );
}

# Headers sent with each delivery:
# X-Webhook-Signature: sha256=<hmac-hex>
# X-Webhook-Id: <webhook-id>
# X-Webhook-Event: <event-type>
# Content-Type: application/json

GET/api/v1/projects/:projectId/webhooks/eventsList the events you can subscribe to

List the events you can subscribe to

Use these names in a webhook's events list. meta.groups groups them by area.

{
            "data": ["content.flagged", "content.approved", "content.banned", "content.processed", "run.completed", "run.failed", "scan.completed", "scan.failed", ...],
            "meta": {
              "total": 19,
              "groups": {
                "content": ["content.flagged", "content.approved", "content.banned", "content.processed"],
                "run": ["run.completed", "run.failed"],
                "scan": ["scan.completed", "scan.failed"],
                ...
              }
            }
          }