Webhooks | Subscribr API

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\"]",
    "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:read

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.

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