Webhook Delivery

How PlatformXe delivers event webhooks with signatures and retries.

When an event matches a subscription, PlatformXe delivers a POST request to your webhook URL with a signed payload.

Delivery headers

Every webhook delivery includes these headers:

Header	Description
X-Event-Signature	HMAC-SHA256 signature of the request body
X-Event-Timestamp	ISO 8601 timestamp of when the event was emitted
X-Event-Type	The event type (e.g., email.message.sent)
X-Event-Id	Unique delivery ID for idempotency
Content-Type	application/json

Verifying signatures

Verify the X-Event-Signature header to ensure the webhook came from PlatformXe.

import crypto from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

// In your webhook handler
app.post('/webhooks/platformxe', (req, res) => {
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    req.headers['x-event-signature'] as string,
    'whsec_your_signing_secret',
  );

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

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

Retry policy

Failed deliveries are retried with exponential backoff:

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

A delivery is considered failed if your endpoint returns a non-2xx status code or does not respond within 10 seconds.

After 5 failed attempts, the event is moved to the dead-letter queue. You can inspect and replay dead-letter events from the Tenant Portal.

Payload format

{
  "eventId": "evt_abc123",
  "eventType": "email.message.sent",
  "timestamp": "2026-04-05T14:30:00.000Z",
  "data": {
    "messageId": "msg_xyz789",
    "to": "user@example.com",
    "subject": "Order Confirmation",
    "status": "delivered"
  }
}

Idempotency

Use the X-Event-Id header to deduplicate events. The same event may be delivered more than once due to retries. Store processed event IDs and skip duplicates.