Webhooks guide

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

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

new-lead is still present in the API docs for backward compatibility, but new-contact is the canonical event name moving forward.

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.

Use the dashboard test/send-sample tooling while building your receiver so you can validate payload handling before production traffic.

Security notes

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