Outbound Event Webhooks¶

The XiansAi Server can notify external systems whenever a significant event happens on the platform — for example when a user is added, a tenant is created, or an agent is deleted. You register listener URLs in the server configuration, and the server delivers a signed HTTP POST to each listener that is subscribed to the event.

How it works¶

Events are delivered through a durable outbox so they survive restarts and work correctly even when several server instances run at once.

sequenceDiagram
    participant Service as Business service
    participant Outbox as webhook_deliveries (Mongo)
    participant Dispatcher as Webhook Dispatcher
    participant Listener as Your listener

    Service->>Outbox: Persist one delivery per matching subscription
    Dispatcher->>Outbox: Atomically claim a batch (lease)
    Dispatcher->>Listener: HTTP POST (signed)
    Listener-->>Dispatcher: 2xx = delivered
    Note over Dispatcher,Outbox: Non-2xx / timeout → retry with backoff

1. When an event occurs, the server writes one durable row per matching subscription into the webhook_deliveries collection.
2. A background dispatcher (running on every instance) atomically claims due rows using a short lease, so exactly one instance delivers each row.
3. On a 2xx response the delivery is marked delivered. On failure it is retried with exponential backoff up to the configured maximum, after which it is marked failed and kept for inspection.
4. If an instance crashes mid-delivery, the lease expires and another instance automatically reclaims the row.

Registering a webhook¶

Webhooks are configured under the Webhooks section of your server configuration (appsettings.json or environment variables). Nothing is queued or delivered until the feature is enabled.

Global settings¶

Subscription settings¶

Each entry in Webhooks:Subscriptions describes one listener.

Example (appsettings.json)¶

{
  "Webhooks": {
    "Enabled": true,
    "PollIntervalSeconds": 5,
    "RequestTimeoutSeconds": 10,
    "MaxAttempts": 5,
    "LeaseSeconds": 60,
    "BatchSize": 20,
    "AllowInsecureHttp": false,
    "Subscriptions": [
      {
        "Name": "crm-listener",
        "Url": "https://example.com/hooks/xians",
        "Secret": "a-long-random-shared-secret",
        "EventTypes": ["user.created", "user.tenant.added", "tenant.created"],
        "Enabled": true
      },
      {
        "Name": "audit-sink",
        "Url": "https://audit.internal.example.com/events",
        "Secret": "another-long-random-secret",
        "EventTypes": ["*"],
        "Enabled": true
      }
    ]
  }
}

Request format¶

The dispatcher sends POST <Url> with Content-Type: application/json and the following headers:

Body envelope¶

Every request body has the same envelope. The data object varies by event type.

{
  "eventType": "user.created",
  "eventId": "0f4c9b1e8a...",
  "tenantId": "acme",
  "occurredAt": "2026-07-01T05:00:00Z",
  "actor": {
    "userId": "admin@acme.com",
    "userType": "UserApiKey",
    "tenantId": "acme",
    "roles": ["TenantAdmin"]
  },
  "data": {
    "userId": "user-123",
    "email": "jane@acme.com",
    "name": "Jane Doe",
    "tenantId": "acme",
    "role": "TenantUser"
  }
}

Securing the calls¶

Verify the signature¶

When a Secret is configured, verify every request before trusting it:

1. Read the X-Xians-Timestamp header and reject the request if it is too old (for example, more than a few minutes) to defend against replay attacks.
2. Compute HMAC-SHA256(secret, "{timestamp}.{rawRequestBody}"), hex-encode it, and compare it in constant time with the value after sha256= in the X-Xians-Signature header.
3. Reject the request if the signatures do not match.

import hashlib, hmac, time

def verify(secret: str, timestamp: str, body: bytes, signature_header: str) -> bool:
    # 1. Reject stale requests (5 minute window)
    if abs(time.time() - int(timestamp)) > 300:
        return False
    # 2. Recompute the signature over "{timestamp}.{body}"
    signed = f"{timestamp}.".encode() + body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    # 3. Constant-time compare
    return hmac.compare_digest(expected, signature_header)

Transport hardening¶

• HTTPS is required by default. Set Webhooks:AllowInsecureHttp=true only for trusted internal listeners on plain HTTP, since payloads may contain personal data.
• Redirects are not followed. A 3xx response is treated as a delivery failure. This prevents a compromised listener from redirecting requests toward internal endpoints.
• Minimal client surface. The dispatcher does not read the response body, sends no cookies, and does not decompress responses, limiting the impact of a hostile or misbehaving listener.
• TLS is validated normally. There is no option to bypass certificate validation.

Delivery semantics¶

Delivery is at-least-once. A listener may occasionally receive the same event more than once (for example, if it returns 2xx after a network timeout). Always deduplicate using eventId.

• Respond with any 2xx status to acknowledge receipt.
• Respond quickly. If your processing is slow, accept the request and process it asynchronously; otherwise you risk the RequestTimeoutSeconds timeout and unnecessary retries.
• Failed deliveries are retried with exponential backoff up to MaxAttempts, then marked Failed and retained for inspection.

Supported events¶

Events are published from the server's shared services, so they fire regardless of whether the change came via the Admin API, Agent API, or Web API.

Tenants¶

Users¶

Agents, deployments, and templates¶

Flow definitions¶

Activations¶

Knowledge¶

Secrets, keys, and certificates¶

App integrations¶

Auditing¶

Beyond delivering to listeners, every row in the webhook_deliveries collection records audit fields you can query directly in the database:

Troubleshooting¶

Nothing is delivered: Confirm Webhooks:Enabled is true and that at least one subscription is defined and Enabled.

A listener receives no events but others do: Check the subscription's EventTypes — it may not include the event types you expect. Use ["*"] to receive everything.

Deliveries fail with a redirect: The dispatcher does not follow redirects. Configure the listener at its final URL.

Signature verification fails: Ensure you sign "{timestamp}.{rawBody}" (raw bytes, before any parsing) with the exact Secret, and compare against the value after sha256=.

Server refuses an http:// URL: HTTPS is required unless Webhooks:AllowInsecureHttp is true.