YouTube API / API Reference / Webhooks

Webhooks

GET

/webhooks

Required Permission webhooks:read

Retrieve a paginated list of all webhooks configured for your team.

Request

Parameters

Name Type Description
per_page integer Webhooks per page (default: 15, max: 100)
page integer Page number for pagination (default: 1)

Response (200)

Response Fields

Field Type Description
id string Webhook identifier
url string Webhook URL endpoint
events array Events this webhook is subscribed to
active boolean Whether webhook is active
created_at string ISO 8601 creation timestamp
Response Example 
[
    {
        "id": "webhook_123",
        "url": "https://example.com/webhooks/subscribr",
        "events": [
            "script.generated",
            "idea.created"
        ],
        "active": true,
        "created_at": "2024-01-10T08:00:00Z"
    }
]
POST

/webhooks

Required Permission webhooks:write

Create a new webhook to receive notifications about events in your Subscribr account.

Request

Request Body 
{
    "url": "string (required) - HTTPS URL where webhooks will be sent",
    "events": "array (required) - Events to subscribe to, e.g., [\"script.generated\", \"idea.created\", \"thumbnail.generated\"]",
    "active": "boolean (optional) - Activate webhook immediately (default: true)"
}

Response (201)

Response Fields

Field Type Description
id string Webhook identifier
url string Webhook URL endpoint
events array Subscribed events
active boolean Active status
secret string Secret for HMAC signature verification
created_at string ISO 8601 creation timestamp
Response Example 
{
    "id": "webhook_456",
    "url": "https://example.com/webhooks/subscribr",
    "events": [
        "script.generated",
        "idea.created"
    ],
    "active": true,
    "secret": "whk_secret_abcdef123456",
    "created_at": "2024-01-26T10:00:00Z"
}
GET

/webhooks/{webhook}

Required Permission webhooks:read

Retrieve detailed information about a specific webhook.

Request

Parameters

Name Type Description
webhook string Webhook ID (path parameter)

Response (200)

Response Fields

Field Type Description
id string Webhook identifier
url string Webhook URL endpoint
events array Subscribed events
active boolean Active status
last_triggered_at string|null Last webhook trigger timestamp
created_at string ISO 8601 creation timestamp
Response Example 
{
    "id": "webhook_456",
    "url": "https://example.com/webhooks/subscribr",
    "events": [
        "script.generated",
        "idea.created"
    ],
    "active": true,
    "last_triggered_at": "2024-01-25T14:22:00Z",
    "created_at": "2024-01-26T10:00:00Z"
}
PUT

/webhooks/{webhook}

Required Permission webhooks:write

Update an existing webhook's configuration including URL, events, and active status.

Request

Request Body 
{
    "url": "string (optional) - New webhook URL",
    "events": "array (optional) - Updated list of events",
    "active": "boolean (optional) - Activate or deactivate webhook"
}

Response (200)

Response Fields

Field Type Description
id string Webhook identifier
url string Webhook URL endpoint
events array Subscribed events
active boolean Active status
updated_at string ISO 8601 last update timestamp
Response Example 
{
    "id": "webhook_456",
    "url": "https://example.com/webhooks/subscribr",
    "events": [
        "script.generated"
    ],
    "active": false,
    "updated_at": "2024-01-26T11:00:00Z"
}
DELETE

/webhooks/{webhook}

Required Permission webhooks:write

Delete a webhook. No further events will be sent to the webhook URL.

Request

Parameters

Name Type Description
webhook string Webhook ID (path parameter)

Response (204)

POST

/webhooks/{webhook}/test

Required Permission webhooks:write

Send a test webhook event to your configured URL. Useful for testing your webhook handler.

Request

Parameters

Name Type Description
webhook string Webhook ID (path parameter)

Response (200)

Response Fields

Field Type Description
status string Delivery status (sent, failed)
event_type string Event type sent in test
sent_at string ISO 8601 timestamp when test was sent
Response Example 
{
    "status": "sent",
    "event_type": "webhook.test",
    "sent_at": "2024-01-26T11:30:00Z"
}

Webhook Events

Reference documentation for all webhook events that can be subscribed to.

Webhooks allow you to receive real-time notifications about important events in your Subscribr account. Subscribe to the events you care about and your webhook endpoint will receive POST requests with event details.

Idea Created

idea.created

Triggered when a new video idea is created (manually or via AI generation)

Example Payload 
{
    "type": "idea.created",
    "timestamp": "2024-01-20T09:15:00Z",
    "data": {
        "idea_id": "idea_456",
        "channel_id": "channel_123",
        "title": "New Video Idea"
    }
}

Script Outline Generated

script.outline.generated

Triggered when AI finishes generating a script outline

Example Payload 
{
    "type": "script.outline.generated",
    "timestamp": "2024-01-21T10:30:00Z",
    "data": {
        "script_id": "script_789",
        "channel_id": "channel_123",
        "outline_word_count": 450
    }
}

Script Generated

script.generated

Triggered when AI finishes generating a full video script

Example Payload 
{
    "type": "script.generated",
    "timestamp": "2024-01-21T12:00:00Z",
    "data": {
        "script_id": "script_789",
        "channel_id": "channel_123",
        "script_word_count": 1200
    }
}

Script Export Requested

script.export.requested

Triggered when a script is exported via the API

Example Payload 
{
    "type": "script.export.requested",
    "timestamp": "2024-01-21T14:15:00Z",
    "data": {
        "script_id": "script_789",
        "format": "pdf",
        "export_id": "export_123"
    }
}

Thumbnail Generated

thumbnail.generated

Triggered when a thumbnail generation run completes successfully

Example Payload 
{
    "type": "thumbnail.generated",
    "timestamp": "2026-02-27T10:30:45Z",
    "data": {
        "run_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "channel_id": 15,
        "idea_id": 42,
        "output_urls": [
            "https://subscribr.ai/storage/thumbnails/9b1deb4d_v1.png"
        ]
    }
}

Webhook Test

webhook.test

Triggered when you use the test webhook endpoint

Example Payload 
{
    "type": "webhook.test",
    "timestamp": "2024-01-26T11:30:00Z",
    "data": {
        "message": "This is a test webhook"
    }
}

Webhook Security

Learn how to secure and verify webhook requests from Subscribr.

All webhook requests from Subscribr are signed with HMAC SHA-256. You should verify this signature to ensure the request is authentic and hasn't been tampered with.

The signature is provided in the `X-Subscribr-Signature` header. It's computed using your webhook secret and the raw request body.

javascript 
const crypto = require("crypto");

function verifyWebhookSignature(body, signature, secret) {
  const hash = crypto
    .createHmac("sha256", secret)
    .update(body, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(hash),
    Buffer.from(signature)
  );
}

// In your webhook handler:
const signature = req.headers["x-subscribr-signature"];
const body = req.rawBody; // Raw request body as string
const secret = process.env.WEBHOOK_SECRET;

if (!verifyWebhookSignature(body, signature, secret)) {
  return res.status(401).json({ error: "Invalid signature" });
}

// Process webhook...
res.status(200).json({ success: true });