Webhooks

Webhooks let Aimdoc send real-time JSON events to your systems whenever something important happens (a new session, a new lead, an escalation, etc.).

Creating a webhook

You can configure webhooks from the Aimdoc dashboard:

Navigate to Integrations
Click Webhooks
Click Create new webhook
Add your Endpoint URL and select the event types you want to receive

Event types

Aimdoc currently supports these webhook events:

new_session: A visitor starts a new conversation.
new_lead: A visitor submits contact information and a lead is created.
session_active: An existing session becomes active again.
session_escalated: A conversation is escalated to a human.
buyer_intent_detected: Buyer intent is detected (or triggered by your configuration).
new_question: A question is flagged (for example, when the AI can’t answer).

Payloads

Payload shape depends on the event type. For canonical schemas and sample payloads, see:

Webhooks Reference — event types and payload schemas

Here’s a simplified example payload you might receive for new_lead:

Example: new_lead payload (simplified)

{
  "lead": {
    "id": "lead-uuid",
    "email": "jane.smith@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Tech Solutions",
    "attributes": {}
  },
  "messages": [
    {
      "role": "user",
      "content": "Can you share pricing?",
      "created_at": "2023-08-15T14:30:45.123Z"
    }
  ],
  "agent_id": "agent-uuid",
  "agent_name": "Sales Assistant"
}

Testing

If you’re iterating on your endpoint, use the dashboard’s “test” / “send sample payload” tooling to validate your webhook receiver before enabling it in production.

Security and operational notes

Webhook signature verification is on the roadmap. For now, treat your webhook endpoint URL as a secret (use an unguessable path), and validate requests server-side.

If you permanently decommission a webhook endpoint, returning HTTP 410 (Gone) will cause Aimdoc to automatically remove the subscription.