Webhooks

GET

/webhooks

Required Permission webhooks:read

Retrieve all webhooks configured for your team (not paginated). Returns summary fields including success_rate and last_delivery.

Request

No request body required.

Response (200)

Response Example

{
    "success": true,
    "data": [
        {
            "id": 12,
            "name": "Production notifications",
            "url": "https://example.com/webhooks/subscribr",
            "events": [
                "script.generated",
                "idea.created"
            ],
            "active": true,
            "success_rate": 98.5,
            "last_delivery": null
        }
    ]
}

Response Fields

Field	Type	Description
success	boolean	Request success
data	array	Webhook summaries
data[].id	integer	Webhook ID
data[].name	string	Webhook label
data[].url	string	HTTPS endpoint URL
data[].events	array\|null	Subscribed events; null or empty receives all event types
data[].active	boolean	Whether deliveries are enabled
data[].success_rate	number	Delivery success percentage
data[].last_delivery	object\|null	Most recent delivery summary or null

POST

/webhooks

Required Permission Team admin required webhooks:write

Create a new webhook. Team administrator required. URL must be HTTPS.

Request

JSON body with webhook configuration.

Request Body Fields

Field	Type	Required	Description
name	string	Yes	Unique label per team. Max 255.
url	string	Yes	Public HTTPS URL. Max 500.
events	array	No	Optional. Omit to receive all event types. Allowed: idea.created, script.outline.generated, script.generated, script.export.requested, thumbnail.generated, webhook.test
timeout	integer	No	Delivery timeout in seconds. 5–120. Default 30.

Example Request Body

{
    "name": "Partner hook",
    "url": "https://example.com/webhooks/subscribr",
    "events": [
        "script.generated",
        "idea.created"
    ]
}

Response (201)

Response Example

{
    "success": true,
    "data": {
        "id": 13,
        "name": "Partner hook",
        "url": "https://example.com/webhooks/subscribr",
        "events": [
            "script.generated"
        ],
        "secret": "store-this-secret-once",
        "active": true,
        "timeout": 30
    }
}

Response Fields

Field	Type	Description
success	boolean	Request success
data.id	integer	Webhook ID
data.name	string	Webhook label
data.url	string	Webhook URL
data.events	array\|null	Subscribed events
data.secret	string	HMAC secret (only on create)
data.active	boolean	Active status
data.timeout	integer	Delivery timeout seconds

Error Responses

Status	Error code	Description
403	Only team administrators can create webhooks	Not team admin
422	(validation)	Invalid URL, events, or duplicate name

GET

/webhooks/{webhook}

Required Permission webhooks:read

Retrieve a webhook with recent delivery history (last 20).

Request

No request body required.

Parameters

Name	Type	Description
webhook	integer	Webhook ID (path)

Response (200)

Response Example

{
    "success": true,
    "data": {
        "id": 12,
        "name": "Production notifications",
        "url": "https://example.com/webhooks/subscribr",
        "events": [
            "script.generated",
            "idea.created"
        ],
        "active": true,
        "headers": null,
        "timeout": 30,
        "success_rate": 98.5,
        "deliveries": [
            {
                "id": 901,
                "event_type": "script.generated",
                "status": "success",
                "response_code": 200
            }
        ]
    }
}

Response Fields

Field	Type	Description
success	boolean	Request success
data.id	integer	Webhook ID
data.name	string	Webhook label
data.url	string	HTTPS endpoint
data.events	array\|null	Subscribed events
data.deliveries	array	Recent delivery attempts

PUT

/webhooks/{webhook}

Required Permission Team admin required webhooks:write

Update webhook settings. Team administrator required. All body fields are optional.

Request

JSON body with fields to update.

Parameters

Name	Type	Description
webhook	integer	Webhook ID (path)

Request Body Fields

Field	Type	Required	Description
name	string	No	New label. Max 255.
url	string	No	HTTPS URL. Max 500.
events	array	No	Replace event list (min 1 when provided)
active	boolean	No	Enable or disable deliveries
timeout	integer	No	5–120 seconds

Example Request Body

{
    "active": false
}

Response (200)

Response Example

{
    "success": true,
    "data": {
        "id": 12,
        "name": "Production notifications",
        "url": "https://example.com/webhooks/subscribr",
        "events": [
            "script.generated"
        ],
        "active": false,
        "timeout": 30
    }
}

Response Fields

Field	Type	Description
success	boolean	Request success
data.id	integer	Webhook ID
data.active	boolean	Active status

Error Responses

Status	Error code	Description
403	Only team administrators can update webhooks	Not team admin

DELETE

/webhooks/{webhook}

Required Permission Team admin required webhooks:write

Soft-delete a webhook. Team administrator required.

Request

No request body required.

Parameters

Name	Type	Description
webhook	string	Webhook ID (path parameter)

Response (200)

Response Example

{
    "success": true,
    "message": "Webhook deleted successfully"
}

Response Fields

Field	Type	Description
success	boolean	Request success
message	string	Confirmation message

POST

/webhooks/{webhook}/test

Required Permission webhooks:write

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

Request

No request body required.

Parameters

Name	Type	Description
webhook	string	Webhook ID (path parameter)

Response (200)

Response Example

{
    "success": true,
    "data": {
        "success": true,
        "status_code": 200,
        "response_body": "{\"received\":true}",
        "error": null
    }
}

Response Fields

Field	Type	Description
success	boolean	API request success
data.success	boolean	Whether the test delivery succeeded
data.status_code	integer\|null	HTTP status from your endpoint
data.response_body	string\|null	Response body from your endpoint
data.error	string\|null	Error message if delivery failed

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 a JSON body shaped as { event, timestamp, data }.

Delivery headers include X-Subscribr-Event, X-Subscribr-Delivery, X-Subscribr-Timestamp, and X-Subscribr-Signature (HMAC sha256=… when a secret is configured).

Idea Created

idea.created

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

Example Payload

{
    "event": "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

{
    "event": "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

{
    "event": "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

{
    "event": "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

{
    "event": "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

{
    "event": "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 in the `X-Subscribr-Signature` header as `sha256=` followed by the hex digest of HMAC-SHA256 over the raw JSON body using your webhook secret.

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