Webhook events
The events Ultimo sends to your webhook endpoints, each with its fields and an example. How to set up an endpoint and verify the signature is in the Webhooks guide.
credits.exhaustedThe AI credits are used up; the agent answers 402 until credits are addedcredits.lowAt most 10 % of the period's AI credits are lefthandoff.endedThe handoff ended; the agent answers againhandoff.messageA person of the business wrote in a handoffhandoff.requestedA visitor asked for a person of the business (or one took over)knowledge.operation.completedA knowledge operation (add, change, refresh, delete) finishedknowledge.operation.failedA knowledge operation failedlead.createdAn agent collected a lead, on any channelresponse.completedAn async response finishedresponse.failedAn async response failedwebhook.testSent by POST /v1/webhook-endpoints/{endpoint_id}/test or the portal's Send test button
Headers on every event
Every event arrives as a POST with a JSON body. Check the signature before you trust the body; the Webhooks guide has the code in Node.js and Python.
| Parameter | Type | Description |
|---|---|---|
Ultimo-Signature | stringheader | t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Two v1 values during a secret rotation. |
Ultimo-Event-Id | stringheader | The event id (evt_...). The same on every retry: use it to drop duplicates. |
Ultimo-Event-Type | stringheader | The event type, e.g. lead.created. |
Ultimo-Delivery-Id | stringheader | Id of the delivery (wd_...), the same on its retries. |
Answer with a 2xx status within 10 seconds. Anything else is retried, 8 attempts over about 23 hours, with the same event id. GET /v1/events shows every delivery with its number of attempts for 30 days.
credits.exhausted
The AI credits are used up; the agent answers 402 until credits are added. Sent once per period.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.agent_id | string | The agent's id. |
data.allowance | integer | Plan credits of the current period. |
data.object | string | Always credits. |
data.remaining | integer | Credits left. |
data.unit | string | One of credits, answers. |
data.window_start | string or null | Start of the current billing period, in UTC. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always credits.exhausted. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": null,
"created_at": "2026-11-10T16:30:45Z",
"data": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"allowance": 10000,
"object": "credits",
"remaining": 0,
"unit": "credits",
"window_start": "2026-11-01T00:00:00Z"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "credits.exhausted"
}credits.low
At most 10 % of the period's AI credits are left. Sent once per period.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.agent_id | string | The agent's id. |
data.allowance | integer | Plan credits of the current period. |
data.object | string | Always credits. |
data.remaining | integer | Credits left. |
data.unit | string | One of credits, answers. |
data.window_start | string or null | Start of the current billing period, in UTC. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always credits.low. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": null,
"created_at": "2026-11-10T16:30:45Z",
"data": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"allowance": 10000,
"object": "credits",
"remaining": 900,
"unit": "credits",
"window_start": "2026-11-01T00:00:00Z"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "credits.low"
}handoff.ended
The handoff ended; the agent answers again.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.agent_id | string | The agent's id. |
data.conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
data.ended_reason | string or null | Only on handoff.ended. One of session_ended, returned_to_agent. |
data.object | string | Always handoff. |
data.requested_at | string or null | When the visitor asked for a person, in UTC. |
data.session_id | string | Session id of the conversation. |
data.status | string or null | agent_requested (waiting for a person) or agent_joined. |
data.visitor_name | string or null | The name the visitor gave, if any. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always handoff.ended. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"data": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"ended_reason": "session_ended",
"object": "handoff",
"requested_at": "2026-11-10T16:30:45Z",
"session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
"status": "ended",
"visitor_name": "Anna"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "handoff.ended"
}handoff.message
A person of the business wrote in a handoff.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.agent_id | string | The agent's id. |
data.channel | string | Channel of the conversation, e.g. website or api. |
data.content | string | The text the person wrote. |
data.conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
data.created_at | string or null | When it was created, in UTC (ISO 8601). |
data.id | string | Message id. |
data.object | string | Always message. |
data.role | string | Always staff. |
data.session_id | string | Session id of the conversation. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always handoff.message. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"data": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"channel": "api",
"content": "Hi Anna, Tom here. I will check your order.",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"id": "msg_0000000000002351",
"object": "message",
"role": "staff",
"session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "handoff.message"
}handoff.requested
A visitor asked for a person of the business (or one took over).
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.agent_id | string | The agent's id. |
data.conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
data.ended_reason | string or null | Only on handoff.ended. One of session_ended, returned_to_agent. |
data.object | string | Always handoff. |
data.requested_at | string or null | When the visitor asked for a person, in UTC. |
data.session_id | string | Session id of the conversation. |
data.status | string or null | agent_requested (waiting for a person) or agent_joined. |
data.visitor_name | string or null | The name the visitor gave, if any. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always handoff.requested. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"data": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"object": "handoff",
"requested_at": "2026-11-10T16:30:45Z",
"session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
"status": "agent_requested",
"visitor_name": "Anna"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "handoff.requested"
}knowledge.operation.completed
A knowledge operation (add, change, refresh, delete) finished.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.action | string | What ran: ingest, import, refresh, delete or discover. |
data.agent_id | string | The agent's id. |
data.created_at | string or null | When it was queued, in UTC. |
data.error_code | string or null | Error code when it failed, otherwise null. |
data.finished_at | string or null | When it finished, in UTC. |
data.id | string | Operation id. |
data.object | string | Always operation. |
data.result | object or null | The result, e.g. indexed_knowledge_ids. |
data.status | string | One of completed, failed. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always knowledge.operation.completed. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": null,
"created_at": "2026-11-10T16:30:45Z",
"data": {
"action": "ingest",
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"created_at": "2026-11-10T16:30:45Z",
"error_code": null,
"finished_at": "2026-11-10T16:30:47Z",
"id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
"object": "operation",
"result": {
"indexed_knowledge_ids": [
226069
]
},
"status": "completed"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "knowledge.operation.completed"
}knowledge.operation.failed
A knowledge operation failed. data.error_code says why.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.action | string | What ran: ingest, import, refresh, delete or discover. |
data.agent_id | string | The agent's id. |
data.created_at | string or null | When it was queued, in UTC. |
data.error_code | string or null | Error code when it failed, otherwise null. |
data.finished_at | string or null | When it finished, in UTC. |
data.id | string | Operation id. |
data.object | string | Always operation. |
data.result | object or null | The result, e.g. indexed_knowledge_ids. |
data.status | string | One of completed, failed. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always knowledge.operation.failed. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": null,
"created_at": "2026-11-10T16:30:45Z",
"data": {
"action": "ingest",
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"created_at": "2026-11-10T16:30:45Z",
"error_code": "SOURCE_UNAVAILABLE",
"finished_at": "2026-11-10T16:30:47Z",
"id": "21bc0b41-3ee8-4f14-8e08-e5148524c3c1",
"object": "operation",
"result": null,
"status": "failed"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "knowledge.operation.failed"
}lead.created
An agent collected a lead, on any channel. data.fields holds what the visitor gave.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.agent_id | string | The agent's id. |
data.conversation_id | string or null | conv_... when the lead came from an API conversation. |
data.created_at | string or null | When it was created, in UTC (ISO 8601). |
data.fields | object | What the visitor gave, e.g. name and email. |
data.id | integer | Lead id. |
data.object | string | Always lead. |
data.read | boolean or null | true once it was opened in the portal or marked as read. |
data.session_id | string or null | Internal session id of the conversation (api-conv_... for API conversations). |
data.type | string or null | Kind of lead form, e.g. contact. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always lead.created. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"data": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T17:00:37.539882Z",
"fields": {
"email": "anna@example.com",
"name": "Anna Example"
},
"id": 46,
"object": "lead",
"read": false,
"session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
"type": "contact"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "lead.created"
}response.completed
An async response finished. data is the response object.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.agent_id | string | The agent's id. |
data.choices | array or null | Only with include=["choices"]. |
data.completed_at | string or null | When the answer was finished, in UTC. |
data.conversation_id | string or null | The conversation (conv_...). Send it, or your external_id, with the next message. |
data.created_at | string or null | When it was created, in UTC (ISO 8601). |
data.end_user | object or null | The end_user you sent. |
data.error | object or null | type, code and message when the response failed, otherwise null. |
data.external_id | string or null | Your id of the conversation, if you sent one. |
data.handoff | object | Whether a person of the business was asked to take over. |
data.handoff.requested | boolean | A person of the business has been asked to take over (or has taken over). |
data.handoff.status | string or null | agent_requested (waiting for a person) or agent_joined. null without a handoff. One of agent_requested, agent_joined. |
data.id | string | Response id (resp_...). |
data.input_message_id | string or null | Id of the stored message you sent (msg_...). |
data.metadata | object | The metadata you sent. Default {}. |
data.mode | string | How it was sent: sync, stream or async. One of sync, stream, async. |
data.object | string | Always response. |
data.output | object or null | The answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation. |
data.output.format | string | markdown or text, as you asked. One of markdown, text. |
data.output.language | string or null | Language of the answer as an ISO code, when it was detected. |
data.output.text | string | The answer. |
data.output_message_id | string or null | Id of the stored answer (msg_...). |
data.products | array of objects or null | Only with include=["products"]. |
data.skipped_reason | string or null | Why there is no answer: human_handoff_active (a person has taken over) or auto_response_off (the agent is muted). One of human_handoff_active, auto_response_off. |
data.status | string | queued, in_progress, completed or failed. One of queued, in_progress, completed, failed. |
data.usage | object | What the answer cost. |
data.usage.credits | integer | AI credits booked for this answer. Default 0. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always response.completed. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"data": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"completed_at": "2026-11-10T16:30:47Z",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"end_user": {
"id": "u-17",
"name": "Anna"
},
"error": null,
"external_id": "ticket-4711",
"handoff": {
"requested": false,
"status": null
},
"id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
"input_message_id": "msg_0000000000002346",
"metadata": {
"ticket": "4711"
},
"mode": "async",
"object": "response",
"output": {
"format": "markdown",
"language": "en",
"text": "Hello Anna, the farm shop is open on Saturdays from 9 to 14."
},
"output_message_id": "msg_0000000000002347",
"status": "completed",
"usage": {
"credits": 1
}
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "response.completed"
}response.failed
An async response failed. data.error.code says why.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.agent_id | string | The agent's id. |
data.choices | array or null | Only with include=["choices"]. |
data.completed_at | string or null | When the answer was finished, in UTC. |
data.conversation_id | string or null | The conversation (conv_...). Send it, or your external_id, with the next message. |
data.created_at | string or null | When it was created, in UTC (ISO 8601). |
data.end_user | object or null | The end_user you sent. |
data.error | object or null | type, code and message when the response failed, otherwise null. |
data.external_id | string or null | Your id of the conversation, if you sent one. |
data.handoff | object | Whether a person of the business was asked to take over. |
data.handoff.requested | boolean | A person of the business has been asked to take over (or has taken over). |
data.handoff.status | string or null | agent_requested (waiting for a person) or agent_joined. null without a handoff. One of agent_requested, agent_joined. |
data.id | string | Response id (resp_...). |
data.input_message_id | string or null | Id of the stored message you sent (msg_...). |
data.metadata | object | The metadata you sent. Default {}. |
data.mode | string | How it was sent: sync, stream or async. One of sync, stream, async. |
data.object | string | Always response. |
data.output | object or null | The answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation. |
data.output.format | string | markdown or text, as you asked. One of markdown, text. |
data.output.language | string or null | Language of the answer as an ISO code, when it was detected. |
data.output.text | string | The answer. |
data.output_message_id | string or null | Id of the stored answer (msg_...). |
data.products | array of objects or null | Only with include=["products"]. |
data.skipped_reason | string or null | Why there is no answer: human_handoff_active (a person has taken over) or auto_response_off (the agent is muted). One of human_handoff_active, auto_response_off. |
data.status | string | queued, in_progress, completed or failed. One of queued, in_progress, completed, failed. |
data.usage | object | What the answer cost. |
data.usage.credits | integer | AI credits booked for this answer. Default 0. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always response.failed. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"data": {
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"completed_at": "2026-11-10T16:32:45Z",
"conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
"created_at": "2026-11-10T16:30:45Z",
"end_user": {
"id": "u-17",
"name": "Anna"
},
"error": {
"code": "generation_timeout",
"message": "The agent did not finish within 120 seconds."
},
"external_id": "ticket-4711",
"handoff": {
"requested": false,
"status": null
},
"id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
"input_message_id": null,
"metadata": {
"ticket": "4711"
},
"mode": "async",
"object": "response",
"output": null,
"output_message_id": null,
"status": "failed",
"usage": {
"credits": 0
}
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "response.failed"
}webhook.test
Sent by POST /v1/webhook-endpoints/{endpoint_id}/test or the portal's Send test button.
Payload
| Field | Type | Description |
|---|---|---|
agent_id | string or null | The agent the event is about, if any. |
conversation_id | string or null | The conversation (conv_...) when it came through the API, otherwise null. |
created_at | string | When the event happened, in UTC. |
data | object | The payload, described below. |
data.message | string | A fixed test text. |
data.object | string | Always test. |
id | string | Event id (evt_...). The same on every retry: use it to drop duplicates. |
type | string | Always webhook.test. |
Example
{
"agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
"api_version": "v1",
"conversation_id": null,
"created_at": "2026-11-10T16:30:45Z",
"data": {
"message": "This is a test event from Ultimo.",
"object": "test"
},
"id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
"object": "event",
"type": "webhook.test"
}