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.
- GET
/v1/webhook-endpointsList webhook endpoints - POST
/v1/webhook-endpointsCreate a webhook endpoint - GET
/v1/webhook-endpoints/{endpoint_id}Get a webhook endpoint - PATCH
/v1/webhook-endpoints/{endpoint_id}Change a webhook endpoint - DELETE
/v1/webhook-endpoints/{endpoint_id}Delete a webhook endpoint - POST
/v1/webhook-endpoints/{endpoint_id}/testSend a test event - POST
/v1/webhook-endpoints/{endpoint_id}/rotate-secretRotate the signing secret - GET
/v1/eventsEvents and their deliveries - POST
/v1/events/{event_id}/resendSend an event again
List webhook endpoints
GET/v1/webhook-endpoints
The endpoints of this integration.
Response 200 OK
| Field | Type | Description |
|---|---|---|
data | array of objects | The items on this page. |
data[].created_at | string or null | When it was created, in UTC (ISO 8601). |
data[].description | string or null | Your note on it. |
data[].disabled_reason | string or null | manual, failing or integration_revoked. |
data[].events | array of strings | The event types it receives. See Webhook events. |
data[].failing_since | string or null | Since when deliveries fail. null while they succeed. |
data[].id | string | Endpoint id (we_...). |
data[].integration_id | string | The integration it belongs to (int_...). |
data[].object | string | Always webhook_endpoint. |
data[].secret_last4 | string | Last four characters of the signing secret. |
data[].status | string | active or disabled. One of active, disabled. |
data[].updated_at | string or null | When it was last changed, in UTC. |
data[].url | string | The receiver's address. |
next_cursor | string or null | Pass it as after to get the next page. null on the last page. |
object | string | Always list. |
Example request
curl "https://api.ultimo-bots.com/v1/webhook-endpoints" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/webhook-endpoints",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/webhook-endpoints", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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
Creates an endpoint and returns its signing secret once.
Request body
| Field | Type | Description |
|---|---|---|
eventsrequired | array of strings | Event types to receive. |
urlrequired | string | Public https address of your receiver. Up to 2048 characters. |
description | string | A note for yourself, e.g. CRM sync. Up to 500 characters. |
Response 201 Created
| Field | Type | Description |
|---|---|---|
created_at | string or null | When it was created, in UTC (ISO 8601). |
events | array of strings | The event types it receives. See Webhook events. |
id | string | Endpoint id (we_...). |
integration_id | string | The integration it belongs to (int_...). |
object | string | Always webhook_endpoint. |
secret | string | whsec_... Shown only in this response. Verify signatures with it. |
secret_last4 | string | Last four characters of the signing secret. |
status | string | active or disabled. One of active, disabled. |
url | string | The receiver's address. |
description | string | Your note on it. |
disabled_reason | any | Why the endpoint is paused: manual, failing or integration_revoked. null while it is active. |
failing_since | any | Since when deliveries fail. null while they succeed. |
updated_at | string | When 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"
}'import os, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/webhook-endpoints",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
json={
"description": "CRM sync",
"events": ["lead.created", "response.completed"],
"url": "https://example.com/ultimo/webhooks",
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/webhook-endpoints", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"description": "CRM sync",
"events": [
"lead.created",
"response.completed"
],
"url": "https://example.com/ultimo/webhooks"
})
});
console.log(res.status, await res.json());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}
Parameters
| Parameter | Type | Description |
|---|---|---|
endpoint_idrequired | stringpath | Webhook endpoint id (we_...). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
created_at | string or null | When it was created, in UTC (ISO 8601). |
events | array of strings | The event types it receives. See Webhook events. |
id | string | Endpoint id (we_...). |
integration_id | string | The integration it belongs to (int_...). |
object | string | Always webhook_endpoint. |
secret_last4 | string | Last four characters of the signing secret. |
status | string | active or disabled. One of active, disabled. |
url | string | The receiver's address. |
description | string | Your note on it. |
disabled_reason | any | Why the endpoint is paused: manual, failing or integration_revoked. null while it is active. |
failing_since | any | Since when deliveries fail. null while they succeed. |
updated_at | string | When 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"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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}
Change address, events or description, pause (disabled) or resume (active).
Parameters
| Parameter | Type | Description |
|---|---|---|
endpoint_idrequired | stringpath | Webhook endpoint id (we_...). |
Request body
| Field | Type | Description |
|---|---|---|
description | string or null | A note for yourself. Up to 500 characters. |
events | array of strings or null | Replaces the list of event types. |
status | string or null | disabled pauses the endpoint, active resumes it. One of active, disabled. |
url | string or null | New public https address. Up to 2048 characters. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
created_at | string or null | When it was created, in UTC (ISO 8601). |
events | array of strings | The event types it receives. See Webhook events. |
id | string | Endpoint id (we_...). |
integration_id | string | The integration it belongs to (int_...). |
object | string | Always webhook_endpoint. |
secret_last4 | string | Last four characters of the signing secret. |
status | string | active or disabled. One of active, disabled. |
url | string | The receiver's address. |
description | string | Your note on it. |
disabled_reason | string | Why the endpoint is paused: manual, failing or integration_revoked. null while it is active. |
failing_since | any | Since when deliveries fail. null while they succeed. |
updated_at | string | When 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"
}'import os, requests
r = requests.patch(
"https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
json={
"status": "disabled",
},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY", {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"status": "disabled"
})
});
console.log(res.status, await res.json());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}
Parameters
| Parameter | Type | Description |
|---|---|---|
endpoint_idrequired | stringpath | Webhook endpoint id (we_...). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
deleted | boolean | true: it is deleted. |
id | string | Id of the deleted endpoint. |
object | string | Always webhook_endpoint. |
Example request
curl -X DELETE "https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.delete(
"https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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
Queues a webhook.test event for this endpoint only.
Parameters
| Parameter | Type | Description |
|---|---|---|
endpoint_idrequired | stringpath | Webhook endpoint id (we_...). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
id | string or null | Event id of the test event. null when none was queued. |
object | string | Always event. |
queued | boolean | true when the test event is queued. |
type | string | Always webhook.test. |
Example request
curl -X POST "https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY/test" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY/test",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY/test", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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
A new secret, returned once. The old one keeps signing for 24 hours as a second v1 value.
Parameters
| Parameter | Type | Description |
|---|---|---|
endpoint_idrequired | stringpath | Webhook endpoint id (we_...). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
id | string | Endpoint id. |
previous_secret_valid_until | string | Until when the old secret also signs, 24 hours after the rotation. |
secret | string | whsec_... 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"import os, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY/rotate-secret",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/webhook-endpoints/we_4Hq9ZtB2mK7sX1vN6cR0dLpY/rotate-secret", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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
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
| Parameter | Type | Description |
|---|---|---|
type | stringquery | Only events of this type, e.g. lead.created. Up to 64 characters. |
delivery_status | stringquery | Only events with a delivery in this state. One of pending, delivering, succeeded, failed. |
limit | integerquery | Items per page. Default 25. 1 to 100. |
after | stringquery | The next_cursor of the previous page. Up to 64 characters. |
Response 200 OK
| Field | Type | Description |
|---|---|---|
data | array of objects | The items on this page. |
data[].agent_id | string or null | The agent the event is about, if any. |
data[].api_version | string | Always v1. |
data[].conversation_id | string or null | The conversation the event is about (conv_...), if any. |
data[].created_at | string | When the event happened, in UTC. |
data[].data | object | The event's payload. See Webhook events. |
data[].deliveries | array of objects | Every delivery of the event to your endpoints. |
data[].deliveries[].attempts | integer | Delivery attempts so far. |
data[].deliveries[].created_at | string or null | When it was created, in UTC (ISO 8601). |
data[].deliveries[].delivered_at | string or null | When your endpoint accepted it. |
data[].deliveries[].endpoint_id | string | The endpoint (we_...). |
data[].deliveries[].event_id | string | The event (evt_...). |
data[].deliveries[].event_type | string | The event type. |
data[].deliveries[].id | string | Delivery id (wd_...). |
data[].deliveries[].last_duration_ms | integer or null | How long the last attempt took, in milliseconds. |
data[].deliveries[].last_error | string or null | Error of the last attempt, e.g. a timeout. |
data[].deliveries[].last_status_code | integer or null | HTTP status your endpoint answered last. |
data[].deliveries[].next_attempt_at | string or null | When the next retry runs. null when there is none. |
data[].deliveries[].object | string | Always webhook_delivery. |
data[].deliveries[].status | string | pending, delivering, succeeded or failed (all 8 attempts failed). One of pending, delivering, succeeded, failed. |
data[].id | string | Event id (evt_...). |
data[].object | string | Always event. |
data[].type | string | The event type, e.g. lead.created. |
next_cursor | string or null | Pass it as after to get the next page. null on the last page. |
object | string | Always list. |
Example request
curl "https://api.ultimo-bots.com/v1/events" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.get(
"https://api.ultimo-bots.com/v1/events",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/events", {
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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
Queues every delivery of this event to this integration's endpoints again.
Parameters
| Parameter | Type | Description |
|---|---|---|
event_idrequired | stringpath | Event id (evt_...). |
Response 200 OK
| Field | Type | Description |
|---|---|---|
id | string | Event id. |
object | string | Always event. |
requeued_deliveries | integer | Deliveries queued again. |
Example request
curl -X POST "https://api.ultimo-bots.com/v1/events/evt_7Bn2QwLx0R5tVc8MzK1yHs4D/resend" \
-H "Authorization: Bearer $ULTIMO_API_KEY"import os, requests
r = requests.post(
"https://api.ultimo-bots.com/v1/events/evt_7Bn2QwLx0R5tVc8MzK1yHs4D/resend",
headers={"Authorization": f"Bearer {os.environ['ULTIMO_API_KEY']}"},
timeout=30,
)
print(r.status_code, r.json())const res = await fetch("https://api.ultimo-bots.com/v1/events/evt_7Bn2QwLx0R5tVc8MzK1yHs4D/resend", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ULTIMO_API_KEY}`
}
});
console.log(res.status, await res.json());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.