Webhooks guide

Webhooks let Aimdoc send real-time JSON events to your systems whenever important conversation or service 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

Choosing events

Subscribe only to the events your receiver needs. Common choices include:

• Contact capture events for CRM or marketing automation
• Session and escalation events for conversation workflows
• Buyer-intent events for sales routing
• Visitor-identification events for enrichment workflows
• Email Conversation Started when the email channel is on
• Service Run Completed, Service Run Progress, and Service Run Failed to follow service runs: the result, plan and step changes while a run executes, and errors

The same native catalog appears on Services → Events (with an aimdoc. prefix) so you can subscribe services to Aimdoc events as well as to names your server emits. See Events.

Use the Webhooks Reference to choose canonical event names and implement against the complete payload schemas and examples. Treat the reference as the source of truth when fields change.

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.
• Treat deliveries as at-least-once. The event id is your dedup key.