Manage Webhooks

API reference for creating, updating, listing, and deleting webhook subscriptions.

Create and manage webhook subscriptions to receive event notifications at your HTTP endpoints.

List webhooks

Retrieve all webhook subscriptions for your organization.

GET /api/v1/webhooks

Scope: webhooks:manage

Response

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "wh_abc123def456",
        "name": "Order notifications",
        "url": "https://yourapp.com/webhooks/platformxe",
        "events": ["email.sent", "email.failed"],
        "active": true,
        "createdAt": "2026-04-01T10:00:00.000Z",
        "lastTriggeredAt": "2026-04-05T14:30:00.000Z"
      }
    ]
  }
}

curl

curl https://api.platformxe.com/api/v1/webhooks \
  -H "x-api-key: pxk_live_your_api_key_here"

SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const result = await px.webhooks.list();
console.log(result.data.webhooks);

---

Create a webhook

Register a new webhook subscription.

POST /api/v1/webhooks

Scope: webhooks:manage

Request body

Field	Type	Required	Description
name	string	Yes	Display name for the webhook
url	string	Yes	HTTPS endpoint URL to receive payloads
events	Array<string>	Yes	Event types to subscribe to (e.g. ["email.sent", "file.uploaded"])

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "name": "Order notifications",
    "url": "https://yourapp.com/webhooks/platformxe",
    "events": ["email.sent", "email.failed"],
    "secret": "whsec_abc123def456ghi789...",
    "active": true,
    "createdAt": "2026-04-05T14:30:00.000Z"
  }
}

curl

curl -X POST https://api.platformxe.com/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "name": "Order notifications",
    "url": "https://yourapp.com/webhooks/platformxe",
    "events": ["email.sent", "email.failed"]
  }'

SDK

const result = await px.webhooks.create({
  name: 'Order notifications',
  url: 'https://yourapp.com/webhooks/platformxe',
  events: ['email.sent', 'email.failed'],
});

// Store this secret securely
console.log(result.data.secret);
// "whsec_abc123def456ghi789..."

---

Update a webhook

Update an existing webhook's name, URL, events, or active status.

PATCH /api/v1/webhooks/:id

Scope: webhooks:manage

Request body

Field	Type	Required	Description
name	string	No	Updated display name
url	string	No	Updated endpoint URL
events	Array<string>	No	Updated event subscriptions (replaces existing)
active	boolean	No	Enable or disable the webhook

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "name": "All notifications",
    "url": "https://yourapp.com/webhooks/platformxe",
    "events": ["email.sent", "email.failed", "file.uploaded"],
    "active": true,
    "updatedAt": "2026-04-05T15:00:00.000Z"
  }
}

curl

curl -X PATCH https://api.platformxe.com/api/v1/webhooks/wh_abc123def456 \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "events": ["email.sent", "email.failed", "file.uploaded"]
  }'

---

Delete a webhook

Remove a webhook subscription. Pending deliveries in the retry queue are cancelled.

DELETE /api/v1/webhooks/:id

Scope: webhooks:manage

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123def456",
    "deleted": true
  }
}

curl

curl -X DELETE https://api.platformxe.com/api/v1/webhooks/wh_abc123def456 \
  -H "x-api-key: pxk_live_your_api_key_here"

Error responses

Code	Description
BAD_REQUEST	Missing required fields or invalid URL
NOT_FOUND	Webhook ID does not exist
FORBIDDEN	API key does not have the webhooks:manage scope
RATE_LIMITED	Rate limit exceeded for this API key