Webhooks - Xenia Team API

Overview

Xenia Webhooks provide real-time HTTP notifications when events occur in your workspace. Instead of polling for changes, your application receives instant updates when tasks change status, submissions are completed, or users are activated. Key Capabilities:

Real-time event notifications via HTTP POST
Configurable event subscriptions (subscribe only to events you need)
Secure signature verification using HMAC-SHA256
Automatic retries with exponential backoff
Dead letter queue for failed deliveries with replay capability
Secret rotation with 24-hour grace period

Prerequisites

Before using webhooks:

Feature Flag: WEBHOOKS must be enabled for your workspace
Authentication: Valid API credentials (x-client-key and x-client-secret)
HTTPS Endpoint: Your webhook receiver must use HTTPS (required for production)

Quick Start

Step 1: Create a Webhook Subscription

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-subscriptions" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Task Notifications",
    "url": "https://your-app.com/webhooks/xenia",
    "events": ["task.status_changed", "submission.submitted"]
  }'

Response:

{
  "status": true,
  "code": 201,
  "data": {
    "id": "sub_abc123",
    "name": "My Task Notifications",
    "url": "https://your-app.com/webhooks/xenia",
    "events": ["task.status_changed", "submission.submitted"],
    "secret": "a1b2c3d4e5f6...64-character-hex-string",
    "isActive": true,
    "createdAt": "2024-12-23T10:00:00Z"
  }
}

The secret is only returned once when the subscription is created. Store it securely immediately - you’ll need it to verify webhook signatures.

Step 2: Store the Secret Securely

Store the webhook secret in your environment variables or secrets manager:

# .env file
XENIA_WEBHOOK_SECRET=a1b2c3d4e5f6...

Step 3: Implement Signature Verification

See the Signature Verification section below for implementation details.

Step 4: Test Your Endpoint

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-subscriptions/{subscriptionId}/test" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response:

{
  "status": true,
  "code": 200,
  "data": {
    "success": true,
    "responseStatus": 200,
    "responseTimeMs": 145,
    "message": "Webhook endpoint responded successfully"
  }
}

Event Types

Tier 1 - Critical (Active)

These events are currently available:

Event Type	Description
`task.status_changed`	Task status transitions (e.g., Open → In Progress → Completed)
`submission.submitted`	Checklist submission completed
`submission.approved`	Submission approved in approval workflow
`submission.rejected`	Submission rejected in approval workflow
`user.invited`	User invited to workspace
`user.activated`	User completed onboarding and became active
`user.deactivated`	User deactivated in workspace

Tier 2 - Standard (Coming Soon)

Event Type	Description
`task.created`	New task created
`task.assigned`	Task assignment changed
`recurring_task.instance_created`	New instance of recurring task generated
`submission.approval_required`	Submission requires approval
`template.published`	Checklist template published
`template.archived`	Checklist template archived

Tier 3 - Extended (Future)

Event Type	Description
`bulk_operation.completed`	Bulk operation finished
`export.completed`	Data export ready for download
`location.member_added`	User added to location
`location.member_removed`	User removed from location
`team.member_added`	User added to team
`team.member_removed`	User removed from team

To get the current list of available event types, use the List Event Types endpoint.

Webhook Payload Format

Payload Structure

Every webhook delivery includes a JSON payload with this structure:

{
  "eventId": "evt_abc123def456",
  "eventType": "task.status_changed",
  "timestamp": "2024-12-23T10:30:00.000Z",
  "workspaceId": "ws_xyz789",
  "data": {
    // Event-specific data
  },
  "metadata": {
    "triggeredBy": "user_abc123"
  }
}

Field	Type	Description
`eventId`	string	Unique identifier for this event (use for idempotency)
`eventType`	string	The type of event that occurred
`timestamp`	string	ISO-8601 timestamp when the event occurred
`workspaceId`	string	Workspace where the event occurred
`data`	object	Event-specific payload data
`metadata`	object	Additional context (e.g., who triggered the event)

HTTP Headers

Every webhook request includes these headers:

Header	Description
`Content-Type`	Always `application/json`
`X-Xenia-Signature`	HMAC-SHA256 signature of the payload
`X-Xenia-Timestamp`	Unix timestamp (seconds) when the webhook was sent
`X-Xenia-Event-Id`	Unique event ID (same as `eventId` in payload)
`X-Xenia-Event-Type`	Event type (same as `eventType` in payload)
`X-Xenia-Previous-Signature`	Previous signature (only during secret rotation)
`User-Agent`	`Xenia-Webhooks/1.0`

Receiving Webhooks

Event Payload Examples

task.status_changed

{
  "eventId": "evt_task_001",
  "eventType": "task.status_changed",
  "timestamp": "2024-12-23T10:30:00.000Z",
  "workspaceId": "ws_xyz789",
  "data": {
    "taskId": "task_abc123",
    "title": "Daily Safety Inspection",
    "previousStatus": "Open",
    "newStatus": "Completed",
    "locationId": "loc_downtown",
    "locationName": "Downtown Branch",
    "assignees": [
      {
        "userId": "user_123",
        "name": "John Doe",
        "email": "[email protected]"
      }
    ],
    "completedBy": {
      "userId": "user_123",
      "name": "John Doe"
    },
    "completedAt": "2024-12-23T10:30:00.000Z"
  },
  "metadata": {
    "triggeredBy": "user_123"
  }
}

submission.submitted

{
  "eventId": "evt_sub_001",
  "eventType": "submission.submitted",
  "timestamp": "2024-12-23T11:00:00.000Z",
  "workspaceId": "ws_xyz789",
  "data": {
    "submissionId": "sub_def456",
    "checklistId": "chk_template_001",
    "checklistName": "Opening Checklist",
    "taskId": "task_abc123",
    "taskTitle": "Morning Opening Procedure",
    "locationId": "loc_downtown",
    "locationName": "Downtown Branch",
    "submittedBy": {
      "userId": "user_456",
      "name": "Jane Smith",
      "email": "[email protected]"
    },
    "submittedAt": "2024-12-23T11:00:00.000Z",
    "score": {
      "total": 100,
      "earned": 95,
      "percentage": 95.0
    }
  },
  "metadata": {
    "triggeredBy": "user_456"
  }
}

user.invited

{
  "eventId": "evt_user_001",
  "eventType": "user.invited",
  "timestamp": "2024-12-23T09:00:00.000Z",
  "workspaceId": "ws_xyz789",
  "data": {
    "userId": "user_new789",
    "email": "[email protected]",
    "firstName": "New",
    "lastName": "User",
    "roleId": "role_staff",
    "roleName": "Staff Member",
    "invitedBy": {
      "userId": "user_admin",
      "name": "Admin User"
    },
    "invitedAt": "2024-12-23T09:00:00.000Z"
  },
  "metadata": {
    "triggeredBy": "user_admin"
  }
}

submission.approved

{
  "eventId": "evt_approval_001",
  "eventType": "submission.approved",
  "timestamp": "2024-12-23T14:00:00.000Z",
  "workspaceId": "ws_xyz789",
  "data": {
    "submissionId": "sub_def456",
    "checklistId": "chk_template_001",
    "checklistName": "Safety Audit",
    "approvedBy": {
      "userId": "user_manager",
      "name": "Manager Name"
    },
    "approvedAt": "2024-12-23T14:00:00.000Z",
    "approvalStep": 1,
    "totalSteps": 2,
    "comments": "Looks good, approved."
  },
  "metadata": {
    "triggeredBy": "user_manager"
  }
}

user.activated

{
  "eventId": "evt_user_002",
  "eventType": "user.activated",
  "timestamp": "2024-12-23T10:00:00.000Z",
  "workspaceId": "ws_xyz789",
  "data": {
    "userId": "user_new789",
    "email": "[email protected]",
    "firstName": "New",
    "lastName": "User",
    "roleId": "role_staff",
    "roleName": "Staff Member",
    "activatedAt": "2024-12-23T10:00:00.000Z"
  },
  "metadata": {
    "triggeredBy": "user_new789"
  }
}

Signature Verification

Always verify webhook signatures to ensure requests are genuinely from Xenia and haven’t been tampered with.

Algorithm

The signature is computed as:

HMAC-SHA256(secret, timestamp + "." + JSON.stringify(payload))

Verification Steps

Extract the X-Xenia-Timestamp and X-Xenia-Signature headers
Check that the timestamp is within 5 minutes of current time (prevents replay attacks)
Compute the expected signature using your webhook secret
Compare signatures using a timing-safe comparison

Always verify webhook signatures in production. Skipping verification exposes your application to spoofed requests, replay attacks, and man-in-the-middle attacks.

Implementation Examples

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  // Check timestamp freshness (5-minute tolerance)
  const currentTime = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTime - parseInt(timestamp)) > 300) {
    throw new Error('Webhook timestamp too old');
  }

  // Compute expected signature
  const signaturePayload = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signaturePayload)
    .digest('hex');

  // Timing-safe comparison
  if (!crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )) {
    throw new Error('Invalid webhook signature');
  }

  return true;
}

// Express middleware example
app.post('/webhooks/xenia', express.json(), (req, res) => {
  try {
    verifyWebhookSignature(
      req.body,
      req.headers['x-xenia-signature'],
      req.headers['x-xenia-timestamp'],
      process.env.XENIA_WEBHOOK_SECRET
    );

    // Process the webhook
    const { eventType, data } = req.body;
    console.log(`Received ${eventType}:`, data);

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

    // Process asynchronously if needed
    processWebhookAsync(req.body);
  } catch (error) {
    console.error('Webhook verification failed:', error.message);
    res.status(401).send('Unauthorized');
  }
});

Handling Secret Rotation

During secret rotation, webhooks include both the current and previous signature:

function verifyWithRotation(payload, headers, currentSecret, previousSecret) {
  const { 'x-xenia-signature': signature, 'x-xenia-timestamp': timestamp } = headers;
  const previousSignature = headers['x-xenia-previous-signature'];

  // Try current secret first
  try {
    return verifyWebhookSignature(payload, signature, timestamp, currentSecret);
  } catch (e) {
    // If rotation is in progress, try previous secret
    if (previousSignature && previousSecret) {
      return verifyWebhookSignature(payload, previousSignature, timestamp, previousSecret);
    }
    throw e;
  }
}

Retry Logic & Delivery

Delivery Behavior

Setting	Value
Timeout	30 seconds
Max Attempts	5
Backoff Schedule	1s, 2s, 4s, 8s, 16s (exponential)
Success Codes	200-299

Response Handling

Response	Behavior
`2xx`	Success - no retry
`429` (Rate Limited)	Retry with backoff
`5xx` (Server Error)	Retry with backoff
Timeout	Retry with backoff
Connection Error	Retry with backoff
`4xx` (except 429)	Non-retryable - moves to dead letter queue immediately

Auto-Disable

Subscriptions are automatically disabled after too many consecutive failures. To re-enable:

curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-subscriptions/{subscriptionId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"isActive": true}'

Return a 200 response immediately and process webhooks asynchronously to avoid timeouts. Most webhook handlers should complete in under 1 second.

Dead Letter Queue

Failed webhooks (after 5 retry attempts) are moved to a dead letter queue with 28-day retention.

Viewing Dead Letters

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-dead-letter?subscriptionId={subscriptionId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Replaying Failed Webhooks

Single Replay:

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-dead-letter/{id}/replay" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Bulk Replay:

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-dead-letter/bulk-replay" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionId": "sub_abc123",
    "eventType": "task.status_changed"
  }'

Bulk replay requires at least one filter (subscriptionId or eventType) and processes a maximum of 100 items per request.

Secret Rotation

Rotate your webhook secret periodically for security. During rotation, both old and new secrets are valid for 24 hours.

Rotation Workflow

Initiate Rotation:

curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-subscriptions/{subscriptionId}/rotate-secret" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response:

{
  "status": true,
  "code": 200,
  "data": {
    "secret": "new_secret_64_char_hex...",
    "previousSecretValidUntil": "2024-12-24T10:00:00Z"
  }
}

Update Your Application: Deploy the new secret to your webhook handler
Verify Both Secrets: During the 24-hour grace period, verify against both signatures
Complete Migration: After 24 hours, only the new secret is valid

During rotation, all webhook deliveries include both X-Xenia-Signature (new secret) and X-Xenia-Previous-Signature (old secret) headers.

Subscription Configuration

Create/Update Options

Field	Type	Required	Description
`name`	string	Yes	Subscription name (max 255 chars)
`url`	string	Yes	HTTPS URL to receive webhooks (max 2048 chars)
`events`	array	Yes	Event types to subscribe to (1-50 events)
`description`	string	No	Description (max 2000 chars)
`rateLimit`	integer	No	Requests per minute (1-1000, default: 100)
`metadata`	object	No	Custom key-value pairs
`isActive`	boolean	No	Enable/disable subscription

Example: Update Subscription

curl -X PATCH "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-subscriptions/{subscriptionId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["task.status_changed", "submission.submitted", "user.activated"],
    "rateLimit": 200,
    "metadata": {
      "environment": "production",
      "team": "operations"
    }
  }'

Monitoring & Analytics

Workspace Statistics

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-stats?period=7d" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response:

{
  "status": true,
  "code": 200,
  "data": {
    "period": "7d",
    "totalDeliveries": 1250,
    "successfulDeliveries": 1230,
    "failedDeliveries": 20,
    "successRate": 98.4,
    "averageLatencyMs": 145,
    "byEventType": {
      "task.status_changed": 800,
      "submission.submitted": 350,
      "user.activated": 100
    }
  }
}

Subscription Logs

curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/webhook-subscriptions/{subscriptionId}/logs?status=failed&limit=50" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Best Practices

Return 200 immediately

Process webhooks asynchronously to avoid timeouts. Your endpoint should acknowledge receipt within a few seconds, then process the data in the background.

app.post('/webhooks', (req, res) => {
  // Acknowledge immediately
  res.status(200).send('OK');

  // Process asynchronously
  queue.add('process-webhook', req.body);
});

Always verify signatures

Never skip signature verification in production. It protects against:

Spoofed requests from attackers
Replay attacks using captured webhooks
Man-in-the-middle modifications

Implement idempotency

Use the eventId to detect and handle duplicate deliveries. Store processed event IDs and skip duplicates:

async function processWebhook(event) {
  const { eventId } = event;

  // Check if already processed
  if (await redis.exists(`webhook:${eventId}`)) {
    return; // Skip duplicate
  }

  // Mark as processing
  await redis.set(`webhook:${eventId}`, 'processing', 'EX', 86400);

  // Process the event
  await handleEvent(event);
}

Rotate secrets regularly

Rotate your webhook secrets periodically (e.g., every 90 days) to limit exposure if a secret is compromised. The 24-hour grace period allows seamless rotation without downtime.

Monitor dead letters

Regularly check the dead letter queue for failed webhooks. Investigate persistent failures - they often indicate endpoint issues or payload handling problems.

Use HTTPS only

All production webhook URLs must use HTTPS. HTTP URLs are rejected to ensure payload confidentiality and integrity.

Troubleshooting

Issue	Solution
WEBHOOKS feature not enabled	Contact your admin to activate the WEBHOOKS feature flag
Invalid signature errors	Verify you’re using the correct secret and JSON stringification matches
Webhook timeouts	Return 200 within 30 seconds; process asynchronously
Events not arriving	Check subscription status (`isActive`) and URL accessibility
Subscription auto-disabled	Fix endpoint issues, then set `isActive: true`
Missing events	Verify the event types are in your subscription’s `events` array
Duplicate events	Implement idempotency using `eventId`

Common Signature Issues

Wrong secret: Ensure you’re using the secret from subscription creation (or the rotated secret)
JSON serialization mismatch: Use JSON.stringify() without pretty-printing or extra spaces
Encoding issues: Ensure UTF-8 encoding throughout
Timestamp format: Use the raw header value, not parsed date object

Task Management

Create, update, and manage tasks that trigger webhooks

Submission Workflow

Learn about checklist submissions that trigger events

User Lifecycle

Manage users and understand user-related events

Error Handling

Handle API errors and webhook failures gracefully

Getting Started

Workflows

Integrations

​Overview

​Prerequisites

​Quick Start

​Step 1: Create a Webhook Subscription

​Step 2: Store the Secret Securely

​Step 3: Implement Signature Verification

​Step 4: Test Your Endpoint

​Event Types

​Tier 1 - Critical (Active)

​Tier 2 - Standard (Coming Soon)

​Tier 3 - Extended (Future)

​Webhook Payload Format

​Payload Structure

​HTTP Headers

​Receiving Webhooks

​Event Payload Examples

​Signature Verification

​Algorithm

​Verification Steps

​Implementation Examples

​Handling Secret Rotation

​Retry Logic & Delivery

​Delivery Behavior

​Response Handling

​Auto-Disable

​Dead Letter Queue

​Viewing Dead Letters

​Replaying Failed Webhooks

​Secret Rotation

​Rotation Workflow

​Subscription Configuration

​Create/Update Options

​Example: Update Subscription

​Monitoring & Analytics

​Workspace Statistics

​Subscription Logs

​Best Practices

​Troubleshooting

​Common Signature Issues

​Related Guides

Task Management

Submission Workflow

User Lifecycle

Error Handling

Overview

Prerequisites

Quick Start

Step 1: Create a Webhook Subscription

Step 2: Store the Secret Securely

Step 3: Implement Signature Verification

Step 4: Test Your Endpoint

Event Types

Tier 1 - Critical (Active)

Tier 2 - Standard (Coming Soon)

Tier 3 - Extended (Future)

Webhook Payload Format

Payload Structure

HTTP Headers

Receiving Webhooks

Event Payload Examples

Signature Verification

Algorithm

Verification Steps

Implementation Examples

Handling Secret Rotation

Retry Logic & Delivery

Delivery Behavior

Response Handling

Auto-Disable

Dead Letter Queue

Viewing Dead Letters

Replaying Failed Webhooks

Secret Rotation

Rotation Workflow

Subscription Configuration

Create/Update Options

Example: Update Subscription

Monitoring & Analytics

Workspace Statistics

Subscription Logs

Best Practices

Troubleshooting

Common Signature Issues

Related Guides