Webhooks

ExoVault supports webhook subscriptions to notify external systems when events occur. Webhooks are configured through the dashboard API and deliver HTTP POST requests to your specified URL.

Supported Events#

Creating a Webhook#

POST /api/webhooks
Content-Type: application/json

{
  "url": "https://your-server.com/webhook/exovault",
  "events": ["message.created"],
  "vaultId": "optional-vault-id",
  "filters": {
    "category": ["alert", "task"],
    "priority_gte": 3,
    "targetId": "claude_code"
  }
}

Request Fields#

Filter Options#

Webhook Response#

When a webhook is created, ExoVault returns the subscription details including a secret for signature verification:

{
  "webhook": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook/exovault",
    "secret": "a1b2c3d4e5f6...",
    "events": ["message.created"],
    "vaultId": null,
    "filters": null,
    "isActive": true,
    "createdAt": "2026-02-28T00:00:00Z"
  }
}

Important: Store the secret securely. It is used to verify webhook signatures and is only returned at creation time.

Webhook Delivery#

When a subscribed event fires, ExoVault delivers an HTTP POST to your URL:

POST /webhook/exovault HTTP/1.1
Content-Type: application/json
X-ExoVault-Signature: sha256=...

{
  "event": "message.created",
  "messageId": "msg_abc123",
  "userId": "user_xyz",
  "timestamp": "2026-02-28T12:00:00Z"
}

Signature Verification#

Verify the X-ExoVault-Signature header using HMAC-SHA256 with the webhook secret:

import crypto from "crypto";

function verifySignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

Managing Webhooks#

List Webhooks#

GET /api/webhooks?limit=50&offset=0

Update a Webhook#

PATCH /api/webhooks
Content-Type: application/json

{
  "id": "wh_abc123",
  "isActive": false,
  "url": "https://new-url.com/webhook",
  "events": ["message.created", "message.acknowledged"],
  "filters": null
}

Delete a Webhook#

DELETE /api/webhooks?id=wh_abc123

Error Handling#

ExoVault tracks delivery failures per webhook:

• Error count increments on each failed delivery
• Last error stores the most recent failure message
• When re-enabling a webhook (isActive: true), the error count resets to 0

Webhooks are not automatically disabled after failures, but monitoring the error count through the dashboard is recommended.

Event Flow#

The typical event flow for message webhooks:

1. An agent calls POST /api/agent/send-message
2. The message is encrypted and stored
3. An agent-message/created event fires via Inngest
4. ExoVault checks for matching webhook subscriptions
5. Matching webhooks receive HTTP POST deliveries

Related Pages#

• Agent Routes -- API endpoints that trigger events
• API Overview -- Base URL and auth
• Error Handling -- Error response format