Webhooks

Receive real-time HTTP notifications when important events occur in your Elysium Nexus tenant. Built with automatic retries, HMAC verification, and circuit breakers.

How It Works

Subscribe to Events

Real-time Delivery

Receive HTTP POST requests to your endpoint within seconds of events occurring in your tenant.

Secure & Verified

Every webhook includes an HMAC-SHA256 signature in the headers for payload verification.

Built for Reliability

Exponential Backoff Retries

Failed deliveries are retried with exponential backoff: 1 min, 5 min, 30 min, 2 hours, 6 hours, up to 24 hours. No events are lost.

Idempotency Keys

Every event includes a unique idempotency key so your handler can safely deduplicate retried deliveries.

Available Events

Event	Description
`bhi.calculated`	Fired when BHI is calculated for a customer
`workflow.completed`	Fired when a workflow run completes
`workflow.failed`	Fired when a workflow run fails
`customer.risk_alert`	Fired when a customer BHI drops below threshold
`nba.generated`	Fired when new recommendations are generated

Example Payload

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Elysium-Signature: sha256=a1b2c3d4...
X-Elysium-Event: bhi.calculated
X-Idempotency-Key: evt_abc123

{
  "id": "evt_abc123",
  "type": "bhi.calculated",
  "timestamp": "2025-01-15T10:30:00Z",
  "tenantId": "your-tenant-id",
  "data": {
    "customerId": "cust-456",
    "bhiOverall": 72.5,
    "bhiBand": "good",
    "trend": "improving",
    "alerts": []
  }
}

Verifying Signatures

Every webhook request includes an X-Elysium-Signature header. Verify it using HMAC-SHA256 with your webhook secret:

import crypto from 'crypto';

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