Manage Subscriptions

Create, list, update, and delete event subscriptions.

Event subscriptions connect platform events to your webhook endpoints.

Scope: events:manage

Rate limit: 1,000/hr

Create a subscription

POST /api/v1/events/subscriptions

Field	Type	Required	Description
eventType	string	Yes	Event pattern (supports wildcards)
webhookUrl	string	Yes	HTTPS URL to deliver events to
secret	string	Yes	Secret for HMAC-SHA256 signature verification
description	string	No	Human-readable label

curl -X POST https://api.platformxe.com/api/v1/events/subscriptions \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "eventType": "email.message.*",
    "webhookUrl": "https://your-app.com/webhooks/email",
    "secret": "whsec_your_signing_secret",
    "description": "Track all email delivery events"
  }'

await px.createEventSubscription({
  eventType: 'email.message.*',
  webhookUrl: 'https://your-app.com/webhooks/email',
  secret: 'whsec_your_signing_secret',
  description: 'Track all email delivery events',
});

List subscriptions

GET /api/v1/events/subscriptions

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

Update a subscription

PATCH /api/v1/events/subscriptions/:id

curl -X PATCH https://api.platformxe.com/api/v1/events/subscriptions/sub_abc123 \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "webhookUrl": "https://your-app.com/webhooks/email-v2",
    "enabled": true
  }'

Delete a subscription

DELETE /api/v1/events/subscriptions/:id

curl -X DELETE https://api.platformxe.com/api/v1/events/subscriptions/sub_abc123 \
  -H "x-api-key: pxk_live_your_api_key_here"

Error responses

Code	Description
BAD_REQUEST	Invalid webhook URL or missing event type
FORBIDDEN	API key missing events:manage scope
NOT_FOUND	Subscription does not exist