Webhooks

SDK methods for managing outbound webhooks.

The px client provides methods for managing outbound webhook endpoints that receive event notifications from PlatformXe.

List webhooks

const result = await px.listWebhooks();

for (const webhook of result.data.webhooks) {
  console.log(`${webhook.id}: ${webhook.url} (${webhook.enabled ? 'active' : 'disabled'})`);
}

Response type

interface Webhook {
  id: string;
  url: string;
  events: string[];
  enabled: boolean;
  secret: string;
  createdAt: string;
}

Create a webhook

const result = await px.createWebhook({
  url: 'https://your-app.com/webhooks/platformxe',
  events: ['email.message.*', 'permissions.role.*'],
  secret: 'whsec_your_signing_secret',
});

console.log(result.data.id); // "whk_abc123"

Parameters

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint URL
events	string[]	Yes	Event patterns to subscribe to
secret	string	Yes	Secret for HMAC-SHA256 verification

Update a webhook

await px.updateWebhook('whk_abc123', {
  url: 'https://your-app.com/webhooks/v2',
  enabled: true,
});

Delete a webhook

await px.deleteWebhook('whk_abc123');

Verify webhook signature

The SDK includes a utility for verifying incoming webhook signatures:

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

app.post('/webhooks/platformxe', (req, res) => {
  const isValid = verifyWebhookSignature({
    body: JSON.stringify(req.body),
    signature: req.headers['x-event-signature'] as string,
    secret: 'whsec_your_signing_secret',
  });

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process event
  res.status(200).send('OK');
});

Scopes required

Method	Scope
px.listWebhooks()	webhooks:manage
px.createWebhook()	webhooks:manage
px.updateWebhook()	webhooks:manage
px.deleteWebhook()	webhooks:manage