Webhooks

Webhooks let your server receive real-time POST requests whenever key events happen in your AIChatVault workspace — new leads captured, conversations started or ended, or messages received. Webhooks are registered at the organisation level and fire for all agents in your workspace.

Supported events

Registering a webhook via API

Use POST /api/v1/webhooks to register a webhook endpoint:

curl -X POST https://aichatvault.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/aichatvault",
    "events": ["lead_captured", "conversation_started"],
    "name": "My Production Webhook"
  }'

# Response
{
  "success": true,
  "message": "Webhook registered successfully",
  "data": {
    "id": 12,
    "url": "https://yourapp.com/webhooks/aichatvault",
    "events": ["lead_captured", "conversation_started"],
    "is_active": true
  }
}

Listing webhooks

GET /api/v1/webhooks

# Response includes delivery stats
{
  "success": true,
  "data": [
    {
      "id": 12,
      "name": "My Production Webhook",
      "url": "https://yourapp.com/webhooks/aichatvault",
      "events": ["lead_captured", "conversation_started"],
      "is_active": true,
      "total_triggers": 284,
      "failed_triggers": 3,
      "last_triggered_at": "2026-07-24T10:30:00Z",
      "created_at": "2026-06-01T09:00:00Z"
    }
  ]
}

Deleting a webhook

DELETE /api/v1/webhooks/{id}

# Response
{
  "success": true,
  "message": "Webhook deleted successfully"
}

Webhook delivery behaviour

• •Each event fires a POST request to your registered URL with a JSON body.
• •Requests are IPv4 only — your endpoint must be reachable on IPv4.
• •Timeout per request: 10 seconds.
• •Failed deliveries are retried up to 3 times with exponential backoff.
• •total_triggers and failed_triggers in the webhook listing give a running delivery health score.

Example: lead_captured payload

{
  "event": "lead_captured",
  "data": {
    "id": 101,
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1234567890",
    "company": "Acme Corp",
    "message": "I am interested in your product",
    "source": "website",
    "source_url": "https://example.com/pricing",
    "agent": { "id": 3, "name": "Sales Bot", "slug": "sales-bot" },
    "conversation_id": 88,
    "session_id": "sess_abc123xyz",
    "created_at": "2026-07-24T10:30:00Z"
  }
}

Example: conversation_started payload

{
  "event": "conversation_started",
  "data": {
    "id": 88,
    "session_id": "sess_abc123xyz",
    "status": "active",
    "source": "website",
    "source_url": "https://example.com/pricing",
    "agent": { "id": 3, "name": "Sales Bot", "slug": "sales-bot" },
    "visitor": {
      "name": null,
      "email": null,
      "ip": "203.0.113.42",
      "country": "US"
    },
    "started_at": "2026-07-24T10:30:00Z",
    "created_at": "2026-07-24T10:30:00Z"
  }
}