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.

5 min read Updated

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.

ParameterTypeDescription
Ultimo-Signaturestringheadert=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Two v1 values during a secret rotation.
Ultimo-Event-IdstringheaderThe event id (evt_...). The same on every retry: use it to drop duplicates.
Ultimo-Event-TypestringheaderThe event type, e.g. lead.created.
Ultimo-Delivery-IdstringheaderId 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.agent_idstringThe agent's id.
data.allowanceintegerPlan credits of the current period.
data.objectstringAlways credits.
data.remainingintegerCredits left.
data.unitstringOne of credits, answers.
data.window_startstring or nullStart of the current billing period, in UTC.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.agent_idstringThe agent's id.
data.allowanceintegerPlan credits of the current period.
data.objectstringAlways credits.
data.remainingintegerCredits left.
data.unitstringOne of credits, answers.
data.window_startstring or nullStart of the current billing period, in UTC.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.agent_idstringThe agent's id.
data.conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
data.ended_reasonstring or nullOnly on handoff.ended. One of session_ended, returned_to_agent.
data.objectstringAlways handoff.
data.requested_atstring or nullWhen the visitor asked for a person, in UTC.
data.session_idstringSession id of the conversation.
data.statusstring or nullagent_requested (waiting for a person) or agent_joined.
data.visitor_namestring or nullThe name the visitor gave, if any.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.agent_idstringThe agent's id.
data.channelstringChannel of the conversation, e.g. website or api.
data.contentstringThe text the person wrote.
data.conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
data.created_atstring or nullWhen it was created, in UTC (ISO 8601).
data.idstringMessage id.
data.objectstringAlways message.
data.rolestringAlways staff.
data.session_idstringSession id of the conversation.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.agent_idstringThe agent's id.
data.conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
data.ended_reasonstring or nullOnly on handoff.ended. One of session_ended, returned_to_agent.
data.objectstringAlways handoff.
data.requested_atstring or nullWhen the visitor asked for a person, in UTC.
data.session_idstringSession id of the conversation.
data.statusstring or nullagent_requested (waiting for a person) or agent_joined.
data.visitor_namestring or nullThe name the visitor gave, if any.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.actionstringWhat ran: ingest, import, refresh, delete or discover.
data.agent_idstringThe agent's id.
data.created_atstring or nullWhen it was queued, in UTC.
data.error_codestring or nullError code when it failed, otherwise null.
data.finished_atstring or nullWhen it finished, in UTC.
data.idstringOperation id.
data.objectstringAlways operation.
data.resultobject or nullThe result, e.g. indexed_knowledge_ids.
data.statusstringOne of completed, failed.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.actionstringWhat ran: ingest, import, refresh, delete or discover.
data.agent_idstringThe agent's id.
data.created_atstring or nullWhen it was queued, in UTC.
data.error_codestring or nullError code when it failed, otherwise null.
data.finished_atstring or nullWhen it finished, in UTC.
data.idstringOperation id.
data.objectstringAlways operation.
data.resultobject or nullThe result, e.g. indexed_knowledge_ids.
data.statusstringOne of completed, failed.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.agent_idstringThe agent's id.
data.conversation_idstring or nullconv_... when the lead came from an API conversation.
data.created_atstring or nullWhen it was created, in UTC (ISO 8601).
data.fieldsobjectWhat the visitor gave, e.g. name and email.
data.idintegerLead id.
data.objectstringAlways lead.
data.readboolean or nulltrue once it was opened in the portal or marked as read.
data.session_idstring or nullInternal session id of the conversation (api-conv_... for API conversations).
data.typestring or nullKind of lead form, e.g. contact.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.agent_idstringThe agent's id.
data.choicesarray or nullOnly with include=["choices"].
data.completed_atstring or nullWhen the answer was finished, in UTC.
data.conversation_idstring or nullThe conversation (conv_...). Send it, or your external_id, with the next message.
data.created_atstring or nullWhen it was created, in UTC (ISO 8601).
data.end_userobject or nullThe end_user you sent.
data.errorobject or nulltype, code and message when the response failed, otherwise null.
data.external_idstring or nullYour id of the conversation, if you sent one.
data.handoffobjectWhether a person of the business was asked to take over.
data.handoff.requestedbooleanA person of the business has been asked to take over (or has taken over).
data.handoff.statusstring or nullagent_requested (waiting for a person) or agent_joined. null without a handoff. One of agent_requested, agent_joined.
data.idstringResponse id (resp_...).
data.input_message_idstring or nullId of the stored message you sent (msg_...).
data.metadataobjectThe metadata you sent. Default {}.
data.modestringHow it was sent: sync, stream or async. One of sync, stream, async.
data.objectstringAlways response.
data.outputobject or nullThe answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation.
data.output.formatstringmarkdown or text, as you asked. One of markdown, text.
data.output.languagestring or nullLanguage of the answer as an ISO code, when it was detected.
data.output.textstringThe answer.
data.output_message_idstring or nullId of the stored answer (msg_...).
data.productsarray of objects or nullOnly with include=["products"].
data.skipped_reasonstring or nullWhy 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.statusstringqueued, in_progress, completed or failed. One of queued, in_progress, completed, failed.
data.usageobjectWhat the answer cost.
data.usage.creditsintegerAI credits booked for this answer. Default 0.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.agent_idstringThe agent's id.
data.choicesarray or nullOnly with include=["choices"].
data.completed_atstring or nullWhen the answer was finished, in UTC.
data.conversation_idstring or nullThe conversation (conv_...). Send it, or your external_id, with the next message.
data.created_atstring or nullWhen it was created, in UTC (ISO 8601).
data.end_userobject or nullThe end_user you sent.
data.errorobject or nulltype, code and message when the response failed, otherwise null.
data.external_idstring or nullYour id of the conversation, if you sent one.
data.handoffobjectWhether a person of the business was asked to take over.
data.handoff.requestedbooleanA person of the business has been asked to take over (or has taken over).
data.handoff.statusstring or nullagent_requested (waiting for a person) or agent_joined. null without a handoff. One of agent_requested, agent_joined.
data.idstringResponse id (resp_...).
data.input_message_idstring or nullId of the stored message you sent (msg_...).
data.metadataobjectThe metadata you sent. Default {}.
data.modestringHow it was sent: sync, stream or async. One of sync, stream, async.
data.objectstringAlways response.
data.outputobject or nullThe answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation.
data.output.formatstringmarkdown or text, as you asked. One of markdown, text.
data.output.languagestring or nullLanguage of the answer as an ISO code, when it was detected.
data.output.textstringThe answer.
data.output_message_idstring or nullId of the stored answer (msg_...).
data.productsarray of objects or nullOnly with include=["products"].
data.skipped_reasonstring or nullWhy 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.statusstringqueued, in_progress, completed or failed. One of queued, in_progress, completed, failed.
data.usageobjectWhat the answer cost.
data.usage.creditsintegerAI credits booked for this answer. Default 0.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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

FieldTypeDescription
agent_idstring or nullThe agent the event is about, if any.
conversation_idstring or nullThe conversation (conv_...) when it came through the API, otherwise null.
created_atstringWhen the event happened, in UTC.
dataobjectThe payload, described below.
data.messagestringA fixed test text.
data.objectstringAlways test.
idstringEvent id (evt_...). The same on every retry: use it to drop duplicates.
typestringAlways 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"
}

Next steps