Webhooks | Smallest AI Docs

Webhooks notify your systems in real-time during the call lifecycle. Atoms sends an HTTP POST to your URL for each event you subscribe to.

Three events fire per call:

Event	When it fires	Contains
`pre-conversation`	Before the agent speaks	Caller numbers, agent ID, call ID
`post-conversation`	After the call ends	Full transcript, recording URL, call metadata, agent variables
`analytics-completed`	After post-call analytics are computed	Summary, disposition + success metrics, call metadata

All three events share the same callId — use it as the join key when correlating events for the same call.

Managing Webhooks

All webhooks are created and managed from the dashboard.

Location: Left Sidebar → Settings → Webhook

Webhooks dashboard — Webhooks page on dashboard

The table shows all your webhooks with their URL, assigned agents, created date, and status.

Creating a Webhook

Click Create to add a new webhook endpoint.

Field	Description
Endpoint URL	Your server URL that receives the POST requests
Description	Optional human-readable label (e.g. `"Debt Collection Agent's Endpoint"`) — echoed back in every event body

The right panel shows example Flask code for handling webhooks with HMAC signature verification.

Click Add endpoint to save.

Webhook Details

Click any webhook to see its details and subscriptions.

Field	What it shows
Webhook URL	The endpoint receiving events
Description	Your note
Subscriptions	Which agents are using this webhook and what events
Status	Enabled or disabled
Signing Secret	For verifying requests are from Atoms

Adding to an Agent

Once a webhook exists, connect it to your agent.

Location: Agent Editor → Agent Settings → Webhook tab

Webhook in agent — Webhook tab in agent settings

Select your webhook from the list, then check which events (pre-conversation, post-conversation, analytics-completed) you want to receive. The agent will now POST to that endpoint for each subscribed event.

Event envelope

Every webhook event shares the same top-level envelope:

Field	Type	Description
`url`	string	The webhook URL endpoint.
`description`	string	Human-readable label configured on the webhook.
`event`	string	`{agentId}.{eventType}` — e.g. `69fc7dd072a0c1d28d948ace.post-conversation`.
`metadata`	object	Event-specific payload. See per-event sections below.
`id`	string	Unique webhook delivery ID (separate from `callId`).

Common `metadata` fields (present in all events)

Field	Type	Description
`metadata.agentId`	string	The Atoms agent ID that handled the call.
`metadata.eventType`	string	One of `pre-conversation`, `post-conversation`, `analytics-completed`.
`metadata.conversationType`	string	Channel type. Known values: `telephonyOutbound`, `telephonyInbound`.
`metadata.callId`	string	Unique call identifier (e.g. `CALL-1778226705739-7e4c17`).

1. `pre-conversation`

Fired before the agent begins speaking. Use this to enrich CRM data, log call attempts, or gate outbound calls.

`metadata` fields

Field	Type	Description
`agentId`	string	Agent ID.
`eventType`	string	`"pre-conversation"`
`conversationType`	string	e.g. `"telephonyOutbound"`
`toPhone`	string	Destination phone number in E.164 format.
`fromPhone`	string	Originating phone number in E.164 format.
`callId`	string	Unique call ID.

Example body

1 {
2   "url": "https://example.com/webhook",
3   "description": "Debt Collection Agent's Endpoint",
4   "event": "69fc7dd072a0c1d28d948ace.pre-conversation",
5   "metadata": {
6     "agentId": "69fc7dd072a0c1d28d948ace",
7     "eventType": "pre-conversation",
8     "conversationType": "telephonyOutbound",
9     "toPhone": "+916296641821",
10     "fromPhone": "+918035317096",
11     "callId": "CALL-1778226705739-7e4c17"
12   },
13   "id": "69fd96118fd277fc807e4c23"
14 }

pre-conversation does not contain callData, transcript, variables, analytics, or recordingUrl.

2. `post-conversation`

Fired after the call ends. Contains the full transcript, call metadata, recording URL, and all agent variables that were in scope during the conversation.

`metadata` fields

Field	Type	Description
`agentId`	string	Agent ID.
`eventType`	string	`"post-conversation"`
`conversationType`	string	e.g. `"telephonyOutbound"`
`callId`	string	Unique call ID.
`recordingUrl`	string	URL to the composite call recording (`.wav`).
`callData`	object	Call-level metadata — see table below.
`transcript`	array	Ordered list of transcript turns — see table below.
`variables`	object	Key-value map of all agent variables injected into the call.

`metadata.callData`

Field	Type	Description
`fromNumber`	string	Originating phone number (E.164).
`toNumber`	string	Destination phone number (E.164).
`callDuration`	number	Total call duration in seconds (float).
`callStatus`	string	Terminal status. Known values: `completed`, `no-answer`, `busy`, `failed`, `canceled`.
`callDirection`	string	`"telephony_outbound"` or `"telephony_inbound"`.
`answerTime`	string	ISO 8601 timestamp when the call was answered (UTC).
`endTime`	string	ISO 8601 timestamp when the call ended (UTC).

`metadata.transcript[]` (array of objects)

Each element represents one speaking turn.

Field	Type	Description
`role`	string	`"agent"` or `"user"`.
`content`	string	The spoken text for this turn.
`timestamp`	string	ISO 8601 timestamp of when this turn began (UTC).

`metadata.variables`

A flat key-value object. Keys and values are entirely determined by the agent configuration; they are not fixed by the platform. Common examples include agent_name, customer_name, current_date, default_language, plus any domain-specific variables your agent uses (e.g. due_amount, bank_name, total_loan_amount).

The variables object is fully dynamic. New keys can appear at any time depending on the agent’s prompt configuration. Your code should handle unknown keys gracefully — store them in a generic JSON column rather than mapping each to a fixed column.

Example body

1 {
2   "url": "https://example.com/webhook",
3   "description": "Debt Collection Agent's Endpoint",
4   "event": "69fc7dd072a0c1d28d948ace.post-conversation",
5   "metadata": {
6     "agentId": "69fc7dd072a0c1d28d948ace",
7     "eventType": "post-conversation",
8     "conversationType": "telephonyOutbound",
9     "callId": "CALL-1778226705739-7e4c17",
10     "recordingUrl": "https://db2izkvf1oocn.cloudfront.net/call-recordings/CALL-.../composite.wav",
11     "callData": {
12       "answerTime": "2026-05-08T07:51:58.813Z",
13       "callDirection": "telephony_outbound",
14       "callDuration": 49.350622,
15       "callStatus": "completed",
16       "endTime": "2026-05-08T07:52:48.164Z",
17       "fromNumber": "+918035317096",
18       "toNumber": "+916296641821"
19     },
20     "transcript": [
21       { "role": "agent", "content": "नमस्ते, मैं Nisha बोल रही हूँ…", "timestamp": "2026-05-08T07:52:05.123Z" },
22       { "role": "user", "content": "हाँ बोलिए", "timestamp": "2026-05-08T07:52:07.369Z" }
23     ],
24     "variables": {
25       "agent_name": "Nisha",
26       "customer_name": "Rahul Sharma",
27       "due_amount": "29000"
28     }
29   },
30   "id": "69fd96578d7c3809f58ce555"
31 }

3. `analytics-completed`

Fired after Atoms finishes running the configured disposition and success metrics on the transcript. Arrives some time after post-conversation.

`metadata` fields

Field	Type	Description
`agentId`	string	Agent ID.
`eventType`	string	`"analytics-completed"`
`conversationType`	string	e.g. `"telephonyOutbound"`
`callId`	string	Unique call ID.
`analytics`	object	Contains `summary`, `dispositionMetrics`, and `successMetrics`.
`callData`	object	Same structure as `post-conversation.callData` — but the `callDirection` field may be absent.

`metadata.analytics`

Field	Type	Description
`summary`	string	LLM-generated plain-text summary of the call.
`dispositionMetrics`	array	Array of metric objects — see schema below.
`successMetrics`	array	Array of metric objects (same schema as disposition metrics). May be empty `[]`.

`analytics.dispositionMetrics[]` and `analytics.successMetrics[]`

Each metric is a self-describing object. The set of metrics is configured per-agent and can vary.

Field	Type	Description
`identifier`	string	Machine-readable metric name (e.g. `turn_taking_balance`, `escalation_needed`).
`value`	integer / string / boolean	The evaluated result. Type depends on `dispositionMetricType`.
`confidence`	number	Confidence score (0–1).
`reasoning`	string	LLM-generated explanation for the assigned value.
`dispositionMetricPrompt`	string	The prompt/question that was used to evaluate this metric.
`dispositionMetricType`	string	Data type of `value`. One of: `INTEGER`, `STRING`, `BOOLEAN`.

Example body

1 {
2   "url": "https://example.com/webhook",
3   "description": "Debt Collection Agent's Endpoint",
4   "event": "69fc7dd072a0c1d28d948ace.analytics-completed",
5   "metadata": {
6     "agentId": "69fc7dd072a0c1d28d948ace",
7     "eventType": "analytics-completed",
8     "conversationType": "telephonyOutbound",
9     "callId": "CALL-1778226705739-7e4c17",
10     "analytics": {
11       "summary": "The call involved the agent discussing an overdue EMI payment…",
12       "dispositionMetrics": [
13         {
14           "identifier": "turn_taking_balance",
15           "value": 2,
16           "confidence": 1,
17           "reasoning": "The user had 4 speaking turns while the agent had 5…",
18           "dispositionMetricPrompt": "Measure the balance of speaking turns…",
19           "dispositionMetricType": "INTEGER"
20         },
21         {
22           "identifier": "escalation_needed",
23           "value": false,
24           "confidence": 1,
25           "reasoning": "The call did not present complex issues…",
26           "dispositionMetricPrompt": "Based on the interaction, did this call require escalation?",
27           "dispositionMetricType": "BOOLEAN"
28         }
29       ],
30       "successMetrics": []
31     },
32     "callData": {
33       "fromNumber": "+918035317096",
34       "toNumber": "+916296641821",
35       "callDuration": 49.350622,
36       "callStatus": "completed",
37       "answerTime": "2026-05-08T07:51:58.813Z",
38       "endTime": "2026-05-08T07:52:48.164Z"
39     }
40   },
41   "id": "69fd96632b717269846aa433"
42 }

Event lifecycle and ordering

Call initiated
      │
      ▼
┌─────────────────┐
│ pre-conversation│  ← Fired before agent speaks
└────────┬────────┘
         │
   Call in progress…
         │
         ▼
┌──────────────────┐
│ post-conversation│  ← Fired after call ends (has transcript + recording)
└────────┬─────────┘
         │
   Analytics processing…
         │
         ▼
┌─────────────────────┐
│ analytics-completed │  ← Fired after metrics are computed
└─────────────────────┘

All three events share the same callId — use it as the join key.

Integration notes

variables is dynamic — never hard-code column mappings. Store as JSON or iterate keys.
dispositionMetrics / successMetrics are agent-configured — the set of identifiers and their types will differ across agents.
pre-conversation uses toPhone / fromPhone while post-conversation and analytics-completed use toNumber / fromNumber — normalize these in your ingestion layer.
Timestamps are always UTC ISO 8601 strings.
callDuration is a float representing seconds (not milliseconds).
recordingUrl only appears in post-conversation.
transcript only appears in post-conversation.
analytics (summary + metrics) only appears in analytics-completed.

Tips

Verify signatures

Use the signing secret to verify requests actually come from Atoms. The example code in the Create modal shows how.

Handle failures gracefully

If your endpoint is down, events may be lost. Log everything and consider retry logic.

One webhook, multiple agents

You can connect the same webhook to multiple agents. The metadata.agentId field tells you which agent sent the event.

Integrations

Connect Salesforce, Zendesk, and more

API Calls

Make requests during conversations

Managing Webhooks

Creating a Webhook

Webhook Details

Adding to an Agent

Event envelope

Common metadata fields (present in all events)

1. pre-conversation

metadata fields

Example body

2. post-conversation

metadata fields

metadata.callData

metadata.transcript[] (array of objects)

metadata.variables

Example body

3. analytics-completed

metadata fields

metadata.analytics

analytics.dispositionMetrics[] and analytics.successMetrics[]

Example body

Event lifecycle and ordering

Integration notes

Tips

Verify signatures

Handle failures gracefully

One webhook, multiple agents

Related

Common `metadata` fields (present in all events)

1. `pre-conversation`

`metadata` fields

2. `post-conversation`

`metadata` fields

`metadata.callData`

`metadata.transcript[]` (array of objects)

`metadata.variables`

3. `analytics-completed`

`metadata` fields

`metadata.analytics`

`analytics.dispositionMetrics[]` and `analytics.successMetrics[]`