Справочник API

Эндпоинты вебхуков

Эндпоинтом вебхука называется ваш URL, который получает события Gemlead в момент, когда они происходят. На аккаунт можно создать до 10 эндпоинтов. О событиях, их данных и проверке подписи читайте в разделе Вебхуки.

Эндпоинты

GET/v1/webhook_endpoints
POST/v1/webhook_endpoints
GET/v1/webhook_endpoints/:id
PATCH/v1/webhook_endpoints/:id
DELETE/v1/webhook_endpoints/:id
POST/v1/webhook_endpoints/:id/roll_secret
POST/v1/webhook_endpoints/:id/test
GET/v1/webhook_endpoints/:id/deliveries

Объект эндпоинта вебхука

Ваш URL, на который Gemlead отправляет события. О событиях и их проверке см. раздел Вебхуки.

Атрибуты

idstring
Уникальный идентификатор эндпоинта.
objectstring
Всегда webhook_endpoint.
urlstring
HTTPS URL, на который отправляются события.
descriptionstring или null
Ваша заметка об эндпоинте.
eventsмассив strings
Типы событий, которые на него отправляются.
lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
statusstring
Отправляются ли на него события.
enableddisabled
filtersobject
Какие события он получает, по персоне лида. Применяется к событиям любого типа.
disabled_reasonstring или null
Почему он отключён. manual, если его выключили вы, failing, если это сделал Gemlead после 3 дней неудач подряд и не меньше 8 неудачных попыток. null, пока он включён.
manualfailing
secretstring
Секрет подписи, whsec_ и 32 символа. Есть только в ответах на создание и обновление секрета.
created_atstring
Когда создан эндпоинт, ISO 8601.
updated_atstring
Время последнего изменения эндпоинта, ISO 8601.

Объект эндпоинта вебхука

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Список эндпоинтов вебхуков

GET/v1/webhook_endpointsПраво read

Возвращает ваши эндпоинты вебхуков без их секретов.

Параметры запроса

limitinteger
Сколько объектов вернуть, от 1 до 100. По умолчанию 25.
cursorstring
next_cursor предыдущей страницы, чтобы получить следующую. См. раздел Пагинация.

Возвращает

Список объектов эндпоинта вебхука.

GET/v1/webhook_endpoints

curl https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Ответ200

{
  "object": "list",
  "data": [
    {
      "id": "wh3LpX9dKe",
      "object": "webhook_endpoint",
      "url": "https://example.com/webhooks/gemlead",
      "description": "CRM sync",
      "events": ["lead.hot", "reply.received"],
      "status": "enabled",
      "filters": {
        "persona_ids": ["lvWBPnytpS"]
      },
      "disabled_reason": null,
      "created_at": "2026-09-14T09:21:05.300Z",
      "updated_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Создание эндпоинта вебхука

POST/v1/webhook_endpointsПраво write

Регистрирует URL для одного или нескольких типов событий. Сохраните secret из ответа, больше он не показывается.

Параметры тела

urlstringОбязательно
HTTPS URL, доступный из публичного интернета.
eventsмассив stringsОбязательно
Типы событий для отправки.
lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
descriptionstring
Заметка для себя.
filtersobject
Какие события отправлять, по персоне лида.

Возвращает

Новый объект эндпоинта вебхука с его secret.

Ошибки

400parameter_missing
Отсутствует обязательный параметр. Название параметра указано в param.
400parameter_invalid
API не принимает значение параметра. Название параметра указано в param.
400parameter_unknown
В теле есть поле, которое этот эндпоинт не принимает.
400url_invalid
URL не на HTTPS, содержит учётные данные или указывает на частный адрес.
400webhook_endpoint_limit_reached
У аккаунта уже 10 эндпоинтов.

POST/v1/webhook_endpoints

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot", "reply.received"],
    "description": "CRM sync",
    "filters": {
      "persona_ids": ["lvWBPnytpS"]
    }
  }'

Ответ200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z",
  "secret": "whsec_4QeX7nP2kR9tLm3Vb8YzC1dF6hJ0sWuA"
}

Получение эндпоинта вебхука

GET/v1/webhook_endpoints/:idПраво read

Возвращает один эндпоинт вебхука без его секрета.

Параметры пути

idstringОбязательно
ID эндпоинта вебхука.

Возвращает

Объект эндпоинта вебхука.

Ошибки

404resource_missing
В аккаунте ключа нет эндпоинта вебхука с этим ID.

GET/v1/webhook_endpoints/:id

curl https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Ответ200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Изменение эндпоинта вебхука

PATCH/v1/webhook_endpoints/:idПраво write

Меняет эндпоинт. Задайте status значение enabled, чтобы снова включить эндпоинт, отключённый Gemlead. Включение или новый url обнуляют его счётчик неудач.

Параметры пути

idstringОбязательно
ID эндпоинта вебхука.

Параметры тела

urlstring
Новый HTTPS URL.
eventsмассив strings
Типы событий для отправки.
lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
descriptionstring
Заметка для себя.
statusstring
Включить или выключить эндпоинт.
enableddisabled
filtersobject
Какие события отправлять, по персоне лида.

Возвращает

Обновлённый объект эндпоинта вебхука.

Ошибки

404resource_missing
В аккаунте ключа нет эндпоинта вебхука с этим ID.
400parameter_invalid
API не принимает значение параметра. Название параметра указано в param.
400parameter_unknown
В теле есть поле, которое этот эндпоинт не принимает.
400url_invalid
URL не на HTTPS, содержит учётные данные или указывает на частный адрес.

PATCH/v1/webhook_endpoints/:id

curl -X PATCH \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "enabled"
  }'

Ответ200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Удаление эндпоинта вебхука

DELETE/v1/webhook_endpoints/:idПраво write

Удаляет эндпоинт. Доставки, которые ещё ждут повторной отправки, отменяются.

Параметры пути

idstringОбязательно
ID эндпоинта вебхука.

Возвращает

Объект с id эндпоинта и deleted, равным true.

Ошибки

404resource_missing
В аккаунте ключа нет эндпоинта вебхука с этим ID.

DELETE/v1/webhook_endpoints/:id

curl -X DELETE \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Ответ200

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

Обновление секрета подписи

POST/v1/webhook_endpoints/:id/roll_secretПраво write

Сразу заменяет секрет эндпоинта, старый перестаёт работать. Доставки, которые не прошли за это время, отправляются повторно с подписью новым секретом.

Параметры пути

idstringОбязательно
ID эндпоинта вебхука.

Возвращает

Объект эндпоинта вебхука с новым secret.

Ошибки

404resource_missing
В аккаунте ключа нет эндпоинта вебхука с этим ID.

POST/v1/webhook_endpoints/:id/roll_secret

curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/roll_secret \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Ответ200

{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z",
  "secret": "whsec_4QeX7nP2kR9tLm3Vb8YzC1dF6hJ0sWuA"
}

Отправка тестового события

POST/v1/webhook_endpoints/:id/testПраво write

Отправляет пример события первого типа из списка эндпоинта, с data.test, равным true, и ID, которые начинаются с test_. Одна попытка, без повторов.

Параметры пути

idstringОбязательно
ID эндпоинта вебхука.

Возвращает

Объект доставки вебхука с status и status_code, которые вернул ваш эндпоинт.

Ошибки

404resource_missing
В аккаунте ключа нет эндпоинта вебхука с этим ID.

POST/v1/webhook_endpoints/:id/test

curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Ответ200

{
  "id": "dL5qW1zXa8",
  "object": "webhook_delivery",
  "endpoint_id": "wh3LpX9dKe",
  "event_id": "evt_8kQ2vXr4LmT9wPz1Hc6YbN3d",
  "event_type": "lead.hot",
  "status": "succeeded",
  "attempts": 1,
  "status_code": 200,
  "error": null,
  "test": true,
  "next_attempt_at": null,
  "last_attempt_at": "2026-11-06T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Объект доставки вебхука

Одно событие, отправленное на один эндпоинт, с его попытками и последним ответом вашего сервера.

Атрибуты

idstring
Уникальный идентификатор доставки.
objectstring
Всегда webhook_delivery.
endpoint_idstring
Эндпоинт, на который она отправлена.
event_idstring
id отправленного события, тот же, что получил ваш сервер.
event_typestring
Тип события.
lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
statusstring
pending, пока остаются попытки, затем succeeded или failed.
pendingsucceededfailed
attemptsinteger
Сколько попыток уже сделано, не больше 8.
status_codeinteger или null
HTTP-статус вашего последнего ответа. null, если ответа не было, после тайм-аута или ошибки соединения.
errorstring или null
Что пошло не так при последней попытке, например статус и начало вашего ответа или тайм-аут.
testboolean
true для тестового события.
next_attempt_atstring или null
Когда запланирована следующая попытка, пока статус pending.
last_attempt_atstring или null
Когда была сделана последняя попытка.
created_atstring
Когда создана доставка, ISO 8601.

Объект доставки вебхука

{
  "id": "dR7mK2pVn4",
  "object": "webhook_delivery",
  "endpoint_id": "wh3LpX9dKe",
  "event_id": "evt_3Hn7QpW2xZk9LmR4tV8bYc1D",
  "event_type": "reply.received",
  "status": "pending",
  "attempts": 2,
  "status_code": 503,
  "error": "HTTP 503: Service Unavailable",
  "test": false,
  "next_attempt_at": "2026-11-06T08:18:10.000Z",
  "last_attempt_at": "2026-11-06T08:13:10.000Z",
  "created_at": "2026-11-06T08:12:10.000Z"
}

Список доставок

GET/v1/webhook_endpoints/:id/deliveriesПраво read

Возвращает последние доставки эндпоинта, сначала новые, включая тестовые события. Доставки хранятся 30 дней.

Параметры пути

idstringОбязательно
ID эндпоинта вебхука.

Параметры запроса

limitinteger
Сколько доставок вернуть, от 1 до 100. По умолчанию 25.

Возвращает

Список объектов доставки вебхука. У этого списка нет next_cursor, увеличьте limit, чтобы увидеть больше.

Ошибки

404resource_missing
В аккаунте ключа нет эндпоинта вебхука с этим ID.
400parameter_invalid
API не принимает значение параметра. Название параметра указано в param.

GET/v1/webhook_endpoints/:id/deliveries

curl -G \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/deliveries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d limit=10

Ответ200

{
  "object": "list",
  "data": [
    {
      "id": "dR7mK2pVn4",
      "object": "webhook_delivery",
      "endpoint_id": "wh3LpX9dKe",
      "event_id": "evt_3Hn7QpW2xZk9LmR4tV8bYc1D",
      "event_type": "reply.received",
      "status": "pending",
      "attempts": 2,
      "status_code": 503,
      "error": "HTTP 503: Service Unavailable",
      "test": false,
      "next_attempt_at": "2026-11-06T08:18:10.000Z",
      "last_attempt_at": "2026-11-06T08:13:10.000Z",
      "created_at": "2026-11-06T08:12:10.000Z"
    },
    {
      "id": "dL5qW1zXa8",
      "object": "webhook_delivery",
      "endpoint_id": "wh3LpX9dKe",
      "event_id": "evt_8kQ2vXr4LmT9wPz1Hc6YbN3d",
      "event_type": "lead.hot",
      "status": "succeeded",
      "attempts": 1,
      "status_code": 200,
      "error": null,
      "test": true,
      "next_attempt_at": null,
      "last_attempt_at": "2026-11-06T07:45:12.904Z",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}