Webhook Best Practices

Reliable webhook consumption patterns for PlatformXe events.

Follow these practices to build reliable, secure webhook consumers for PlatformXe event delivery.

Always verify signatures

Every webhook includes an X-Event-Signature header. Verify it before processing:

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: process.env.WEBHOOK_SECRET!,
  });

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

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

Respond quickly

PlatformXe expects a response within 10 seconds. If your processing takes longer, accept the webhook immediately and process asynchronously:

app.post('/webhooks/platformxe', async (req, res) => {
  // Verify signature first
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid');
  }

  // Accept immediately
  res.status(200).send('OK');

  // Process asynchronously
  await processEventAsync(req.body);
});

Use idempotency keys

The same event may be delivered more than once due to retries. Use the X-Event-Id header to deduplicate:

const processedEvents = new Set<string>(); // Use Redis in production

app.post('/webhooks/platformxe', (req, res) => {
  const eventId = req.headers['x-event-id'] as string;

  if (processedEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }

  processedEvents.add(eventId);
  // Process the event...
  res.status(200).send('OK');
});

Handle retries gracefully

PlatformXe retries failed deliveries up to 5 times with exponential backoff:

Attempt	Delay
1	Immediate
2	30 seconds
3	2 minutes
4	15 minutes
5	1 hour

Return a 2xx status to acknowledge receipt. Any non-2xx response or timeout triggers a retry.

Monitor the dead-letter queue

After 5 failed attempts, events move to the dead-letter queue. Check the Tenant Portal for dead-lettered events and replay them once you fix the underlying issue.

Security checklist

• Verify X-Event-Signature on every request
• Only accept webhooks over HTTPS
• Use a dedicated webhook endpoint (not a general-purpose API)
• Rotate webhook secrets periodically
• Log event IDs for debugging, not full payloads (they may contain PII)

Recommended architecture

Webhook POST → Signature check → Queue (Redis/SQS) → Worker → Business logic
                    ↓
              200 OK (immediate)