Webhook endpoints

The addresses that receive your integration's webhook events, and the log of the events sent to them. What each event contains is on Webhook events; how to verify the signature is in the Webhooks guide.

7 min read Updated

List webhook endpoints

GET/v1/webhook-endpoints

Permission webhooks:write

The endpoints of this integration.

Response 200 OK

FieldTypeDescription
dataarray of objectsThe items on this page.
data[].created_atstring or nullWhen it was created, in UTC (ISO 8601).
data[].descriptionstring or nullYour note on it.
data[].disabled_reasonstring or nullmanual, failing or integration_revoked.
data[].eventsarray of stringsThe event types it receives. See Webhook events.
data[].failing_sincestring or nullSince when deliveries fail. null while they succeed.
data[].idstringEndpoint id (we_...).
data[].integration_idstringThe integration it belongs to (int_...).
data[].objectstringAlways webhook_endpoint.
data[].secret_last4stringLast four characters of the signing secret.
data[].statusstringactive or disabled. One of active, disabled.
data[].updated_atstring or nullWhen it was last changed, in UTC.
data[].urlstringThe receiver's address.
next_cursorstring or nullPass it as after to get the next page. null on the last page.
objectstringAlways list.

Example request

curl "https://api.ultimo-bots.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "data": [
    {
      "created_at": "2026-11-10T16:30:45Z",
      "description": "CRM sync",
      "disabled_reason": null,
      "events": [
        "lead.created",
        "response.completed"
      ],
      "failing_since": null,
      "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
      "integration_id": "int_5UZEgyPjQc9cfpQlGJB3CuGX",
      "object": "webhook_endpoint",
      "secret_last4": "x9Qe",
      "status": "active",
      "updated_at": "2026-11-10T16:30:45Z",
      "url": "https://example.com/ultimo/webhooks"
    }
  ],
  "next_cursor": null,
  "object": "list"
}

Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.

Create a webhook endpoint

POST/v1/webhook-endpoints

Permission webhooks:writeNeeds an integration with read and change access

Creates an endpoint and returns its signing secret once.

Request body

FieldTypeDescription
eventsrequiredarray of stringsEvent types to receive.
urlrequiredstringPublic https address of your receiver. Up to 2048 characters.
descriptionstringA note for yourself, e.g. CRM sync. Up to 500 characters.

Response 201 Created

FieldTypeDescription
created_atstring or nullWhen it was created, in UTC (ISO 8601).
eventsarray of stringsThe event types it receives. See Webhook events.
idstringEndpoint id (we_...).
integration_idstringThe integration it belongs to (int_...).
objectstringAlways webhook_endpoint.
secretstringwhsec_... Shown only in this response. Verify signatures with it.
secret_last4stringLast four characters of the signing secret.
statusstringactive or disabled. One of active, disabled.
urlstringThe receiver's address.
descriptionstringYour note on it.
disabled_reasonanyWhy the endpoint is paused: manual, failing or integration_revoked. null while it is active.
failing_sinceanySince when deliveries fail. null while they succeed.
updated_atstringWhen it was last changed, in UTC.

Example request

curl -X POST "https://api.ultimo-bots.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $ULTIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "CRM sync",
  "events": [
    "lead.created",
    "response.completed"
  ],
  "url": "https://example.com/ultimo/webhooks"
}'

Response 201 Created

{
  "created_at": "2026-11-10T16:30:45Z",
  "description": "CRM sync",
  "disabled_reason": null,
  "events": [
    "lead.created",
    "response.completed"
  ],
  "failing_since": null,
  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
  "integration_id": "int_5UZEgyPjQc9cfpQlGJB3CuGX",
  "object": "webhook_endpoint",
  "secret": "whsec_3fJ8kQ2mZ7xV1bN6cR0dLpYt5Hs9WgUeAaBbCcDdEe0",
  "secret_last4": "x9Qe",
  "status": "active",
  "updated_at": "2026-11-10T16:30:45Z",
  "url": "https://example.com/ultimo/webhooks"
}

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.

Get a webhook endpoint

GET/v1/webhook-endpoints/{endpoint_id}

Permission webhooks:write

Parameters

ParameterTypeDescription
endpoint_idrequiredstringpathWebhook endpoint id (we_...).

Response 200 OK

FieldTypeDescription
created_atstring or nullWhen it was created, in UTC (ISO 8601).
eventsarray of stringsThe event types it receives. See Webhook events.
idstringEndpoint id (we_...).
integration_idstringThe integration it belongs to (int_...).
objectstringAlways webhook_endpoint.
secret_last4stringLast four characters of the signing secret.
statusstringactive or disabled. One of active, disabled.
urlstringThe receiver's address.
descriptionstringYour note on it.
disabled_reasonanyWhy the endpoint is paused: manual, failing or integration_revoked. null while it is active.
failing_sinceanySince when deliveries fail. null while they succeed.
updated_atstringWhen it was last changed, in UTC.

Example request

curl "https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "created_at": "2026-11-10T16:30:45Z",
  "description": "CRM sync",
  "disabled_reason": null,
  "events": [
    "lead.created",
    "response.completed"
  ],
  "failing_since": null,
  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
  "integration_id": "int_5UZEgyPjQc9cfpQlGJB3CuGX",
  "object": "webhook_endpoint",
  "secret_last4": "x9Qe",
  "status": "active",
  "updated_at": "2026-11-10T16:30:45Z",
  "url": "https://example.com/ultimo/webhooks"
}

Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.

Change a webhook endpoint

PATCH/v1/webhook-endpoints/{endpoint_id}

Permission webhooks:writeNeeds an integration with read and change access

Change address, events or description, pause (disabled) or resume (active).

Parameters

ParameterTypeDescription
endpoint_idrequiredstringpathWebhook endpoint id (we_...).

Request body

FieldTypeDescription
descriptionstring or nullA note for yourself. Up to 500 characters.
eventsarray of strings or nullReplaces the list of event types.
statusstring or nulldisabled pauses the endpoint, active resumes it. One of active, disabled.
urlstring or nullNew public https address. Up to 2048 characters.

Response 200 OK

FieldTypeDescription
created_atstring or nullWhen it was created, in UTC (ISO 8601).
eventsarray of stringsThe event types it receives. See Webhook events.
idstringEndpoint id (we_...).
integration_idstringThe integration it belongs to (int_...).
objectstringAlways webhook_endpoint.
secret_last4stringLast four characters of the signing secret.
statusstringactive or disabled. One of active, disabled.
urlstringThe receiver's address.
descriptionstringYour note on it.
disabled_reasonstringWhy the endpoint is paused: manual, failing or integration_revoked. null while it is active.
failing_sinceanySince when deliveries fail. null while they succeed.
updated_atstringWhen it was last changed, in UTC.

Example request

curl -X PATCH "https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY" \
  -H "Authorization: Bearer $ULTIMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "disabled"
}'

Response 200 OK

{
  "created_at": "2026-11-10T16:30:45Z",
  "description": "CRM sync",
  "disabled_reason": "manual",
  "events": [
    "lead.created",
    "response.completed"
  ],
  "failing_since": null,
  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
  "integration_id": "int_5UZEgyPjQc9cfpQlGJB3CuGX",
  "object": "webhook_endpoint",
  "secret_last4": "x9Qe",
  "status": "disabled",
  "updated_at": "2026-11-10T16:30:45Z",
  "url": "https://example.com/ultimo/webhooks"
}

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.

Delete a webhook endpoint

DELETE/v1/webhook-endpoints/{endpoint_id}

Permission webhooks:writeNeeds an integration with read and change access

Parameters

ParameterTypeDescription
endpoint_idrequiredstringpathWebhook endpoint id (we_...).

Response 200 OK

FieldTypeDescription
deletedbooleantrue: it is deleted.
idstringId of the deleted endpoint.
objectstringAlways webhook_endpoint.

Example request

curl -X DELETE "https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "deleted": true,
  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
  "object": "webhook_endpoint"
}

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.

Send a test event

POST/v1/webhook-endpoints/{endpoint_id}/test

Permission webhooks:writeNeeds an integration with read and change access

Queues a webhook.test event for this endpoint only.

Parameters

ParameterTypeDescription
endpoint_idrequiredstringpathWebhook endpoint id (we_...).

Response 200 OK

FieldTypeDescription
idstring or nullEvent id of the test event. null when none was queued.
objectstringAlways event.
queuedbooleantrue when the test event is queued.
typestringAlways webhook.test.

Example request

curl -X POST "https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY/test" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
  "object": "event",
  "queued": true,
  "type": "webhook.test"
}

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.

Rotate the signing secret

POST/v1/webhook-endpoints/{endpoint_id}/rotate-secret

Permission webhooks:writeNeeds an integration with read and change access

A new secret, returned once. The old one keeps signing for 24 hours as a second v1 value.

Parameters

ParameterTypeDescription
endpoint_idrequiredstringpathWebhook endpoint id (we_...).

Response 200 OK

FieldTypeDescription
idstringEndpoint id.
previous_secret_valid_untilstringUntil when the old secret also signs, 24 hours after the rotation.
secretstringwhsec_... Shown only in this response.

Example request

curl -X POST "https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY/rotate-secret" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
  "previous_secret_valid_until": "2026-11-11T16:30:45Z",
  "secret": "whsec_9aK2mQ7xV1bN6cR0dLpYt5Hs3fJ8WgUeAaBbCcDdEe1"
}

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.

Events and their deliveries

GET/v1/events

Permission webhooks:write

The last 30 days of events sent to this integration's endpoints, newest first, each with its deliveries (status, attempts, last HTTP status, duration).

Parameters

ParameterTypeDescription
typestringqueryOnly events of this type, e.g. lead.created. Up to 64 characters.
delivery_statusstringqueryOnly events with a delivery in this state. One of pending, delivering, succeeded, failed.
limitintegerqueryItems per page. Default 25. 1 to 100.
afterstringqueryThe next_cursor of the previous page. Up to 64 characters.

Response 200 OK

FieldTypeDescription
dataarray of objectsThe items on this page.
data[].agent_idstring or nullThe agent the event is about, if any.
data[].api_versionstringAlways v1.
data[].conversation_idstring or nullThe conversation the event is about (conv_...), if any.
data[].created_atstringWhen the event happened, in UTC.
data[].dataobjectThe event's payload. See Webhook events.
data[].deliveriesarray of objectsEvery delivery of the event to your endpoints.
data[].deliveries[].attemptsintegerDelivery attempts so far.
data[].deliveries[].created_atstring or nullWhen it was created, in UTC (ISO 8601).
data[].deliveries[].delivered_atstring or nullWhen your endpoint accepted it.
data[].deliveries[].endpoint_idstringThe endpoint (we_...).
data[].deliveries[].event_idstringThe event (evt_...).
data[].deliveries[].event_typestringThe event type.
data[].deliveries[].idstringDelivery id (wd_...).
data[].deliveries[].last_duration_msinteger or nullHow long the last attempt took, in milliseconds.
data[].deliveries[].last_errorstring or nullError of the last attempt, e.g. a timeout.
data[].deliveries[].last_status_codeinteger or nullHTTP status your endpoint answered last.
data[].deliveries[].next_attempt_atstring or nullWhen the next retry runs. null when there is none.
data[].deliveries[].objectstringAlways webhook_delivery.
data[].deliveries[].statusstringpending, delivering, succeeded or failed (all 8 attempts failed). One of pending, delivering, succeeded, failed.
data[].idstringEvent id (evt_...).
data[].objectstringAlways event.
data[].typestringThe event type, e.g. lead.created.
next_cursorstring or nullPass it as after to get the next page. null on the last page.
objectstringAlways list.

Example request

curl "https://api.ultimo-bots.com/v1/events" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "data": [
    {
      "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"
      },
      "deliveries": [
        {
          "attempts": 1,
          "created_at": "2026-11-10T16:30:45Z",
          "delivered_at": "2026-11-10T16:30:45Z",
          "endpoint_id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
          "event_id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
          "event_type": "lead.created",
          "id": "wd_2Yc5RkP8mT1xZ7bN4cL0pQdH",
          "last_duration_ms": 142,
          "last_error": null,
          "last_status_code": 200,
          "next_attempt_at": null,
          "object": "webhook_delivery",
          "status": "succeeded"
        }
      ],
      "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
      "object": "event",
      "type": "lead.created"
    }
  ],
  "next_cursor": null,
  "object": "list"
}

Errors: 400, 401, 403, 404, 422, 429, 500, 503. What each code means: Error codes.

Send an event again

POST/v1/events/{event_id}/resend

Permission webhooks:writeNeeds an integration with read and change access

Queues every delivery of this event to this integration's endpoints again.

Parameters

ParameterTypeDescription
event_idrequiredstringpathEvent id (evt_...).

Response 200 OK

FieldTypeDescription
idstringEvent id.
objectstringAlways event.
requeued_deliveriesintegerDeliveries queued again.

Example request

curl -X POST "https://api.ultimo-bots.com/v1/events/evt_7Bn2QwLx0R5tVc8MzK1yHs4D/resend" \
  -H "Authorization: Bearer $ULTIMO_API_KEY"

Response 200 OK

{
  "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
  "object": "event",
  "requeued_deliveries": 1
}

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503. What each code means: Error codes.

Next steps