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.

Payload shape

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

• agent_id and agent_name
• 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)

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.