Webhooks

Webhooks let Aimdoc send real-time JSON events to your systems whenever important conversation activity happens.

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 choose the event types you want

Event types

Aimdoc currently supports these webhook events:

• new-session: a visitor starts a new conversation.
• new-contact: contact details are captured.
• session-active: an existing conversation becomes active again.
• session-escalated: a conversation is escalated to a human.
• buyer-intent-detected: buyer intent is detected.
• new-question: a question is flagged.
• visitor-identified: a visitor is identified or materially enriched with person/company data.

Payload shape

Payload fields vary by event type. Most events include some combination of:

• agent_id and agent_name
• visitor for visitor-identity snapshots
• conversation (with IDs/timestamps and optional messages)
• lead for contact-capture events
• event-specific fields like escalation_reason or buyer_intent_reason

Here is a simplified new-contact style payload:

{
  "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"
}

For canonical schemas and full examples, use:

• Webhooks Reference (Redoc)

Here is a simplified visitor-identified style payload:

{
  "visitor": {
    "visitor_id": "visitor-uuid",
    "lead_id": "lead-uuid",
    "latest_conversation_id": "conversation-uuid",
    "summary": {
      "status": "identified",
      "display_name": "Jane Doe",
      "subtitle": "VP Marketing at Acme"
    },
    "person": {
      "email": "jane.doe@example.com",
      "title": "VP Marketing"
    },
    "company": {
      "name": "Acme",
      "domain": "acme.com"
    }
  },
  "conversation": {
    "id": "conversation-uuid",
    "created_at": "2023-08-15T14:30:45.123Z",
    "last_activity": "2023-08-15T14:32:10.000Z"
  },
  "agent_id": "agent-uuid",
  "agent_name": "Sales Assistant"
}

Delivery behavior

• Aimdoc sends webhook payloads as POST requests with JSON bodies.
• Return a 2xx response quickly to acknowledge receipt.
• If delivery fails, Aimdoc retries up to 3 times with exponential backoff.
• If your endpoint is permanently decommissioned, return 410 Gone to remove the webhook subscription automatically.

Security notes

• Use HTTPS endpoints only.
• Treat your webhook URL as a secret (use an unguessable path).
• Validate request payloads server-side before processing.