API EN
Ранний доступ. Ключи выдаются по запросу. Как получить ключ

Адреса вебхуков

Адреса вебхуков кабинета, их состояние и журнал доставок. Нужны право webhooks:read и ключ на все пространства и кампании.

Маршруты

#Объект WebhookEndpoint

Адрес вебхука кабинета и его состояние. Полного адреса нет: в пути бывает секрет, поэтому видно только имя сервера. Значений дополнительных заголовков тоже нет, только их имена.

Поля

  • objectstring
    Тип объекта, всегда webhook_endpoint.
  • idstring (uuid)
    Идентификатор адреса.
  • statusstring
    active получает события, paused на паузе, disabled выключен: сам или по коду 410 получателя. Значения: active paused disabled
  • disabled_reasonstring или null
    Почему адрес выключен или на паузе: gone (получатель ответил 410), failing_72h (ошибки больше 3 суток), plan (тариф без вебхуков), other. У работающего адреса null. Значения: gone failing_72h plan other
  • hoststring
    Имя сервера получателя. До 253 знаков.
  • descriptionstring или null
    Описание из кабинета или null. До 500 знаков.
  • event_typesarray of string
    Типы событий, которые получает адрес. До 20 элементов.
  • workspace_idsarray of string или null
    Пространства, события которых получает адрес. null: все пространства. До 50 элементов.
  • campaign_idsarray of string или null
    Кампании, события которых получает адрес. null: все кампании. До 500 элементов.
  • include_message_textboolean
    Передается ли текст ответа лида.
  • header_namesarray of string
    Имена дополнительных заголовков, без значений. До 5 элементов.
  • failing_sincestring (date-time) или null
    С какого момента адрес не принимает события или null, если последняя попытка успешна.
  • consecutive_failuresinteger
    Неудачных попыток подряд.
  • last_success_atstring (date-time) или null
    Время последней успешной доставки или null.
  • versioninteger
    Номер версии настроек адреса. Растет при каждом изменении.
  • created_atstring (date-time)
    Когда адрес добавлен.
  • updated_atstring (date-time)
    Когда настройки адреса менялись последний раз.
  • deliveriesobject
    Сводка доставок.
    Вложенные поля
    • pendinginteger
      Сколько событий ждут отправки.
    • succeeded_24hinteger
      Доставлено за последние сутки.
    • failed_24hinteger
      Не доставлено за последние сутки.
    • last_finished_atstring (date-time) или null
      Когда закончилась последняя доставка или null.
    • last_status_codeinteger или null
      Код ответа получателя на последнюю доставку или null.
    • last_error_classstring или null
      Класс последней ошибки: invalid_url, dns, ssrf_blocked, connect, tls, timeout, http, payload_too_large, unknown или null. Значения: invalid_url dns ssrf_blocked connect tls timeout http payload_too_large unknown
WebhookEndpoint
{
  "object": "webhook_endpoint",
  "id": "6b2d9f40-3c1e-4a7b-8f5d-2e9c0a1b7d64",
  "status": "active",
  "disabled_reason": null,
  "host": "hooks.example.com",
  "description": "CRM",
  "event_types": [
    "lead.first_message_sent",
    "lead.replied"
  ],
  "workspace_ids": null,
  "campaign_ids": null,
  "include_message_text": false,
  "header_names": [
    "x-api-key"
  ],
  "failing_since": null,
  "consecutive_failures": 0,
  "last_success_at": "2026-10-27T09:15:03.000Z",
  "version": 2,
  "created_at": "2026-10-20T08:00:00.000Z",
  "updated_at": "2026-10-22T12:30:00.000Z",
  "deliveries": {
    "pending": 0,
    "succeeded_24h": 38,
    "failed_24h": 0,
    "last_finished_at": "2026-10-27T09:15:03.000Z",
    "last_status_code": 200,
    "last_error_class": null
  }
}

#Объект WebhookDelivery

Одна доставка события на адрес вебхука. Данных лида нет: само событие отдает лента событий по event_id.

Поля

  • objectstring
    Тип объекта, всегда webhook_delivery.
  • idstring (uuid)
    Идентификатор доставки.
  • endpoint_idstring (uuid)
    Адрес вебхука.
  • event_idstring
    Идентификатор события: тот же, что в заголовке webhook-id и в ленте событий. Формат ^evt_[a-f0-9]{32}$.
  • event_typestring или null
    Тип события, webhook.test для проверочного, unknown для неизвестного или null, если события уже нет. Значения: lead.first_message_sent lead.replied message.received lead.status_changed campaign.status_changed account.status_changed message.sent message.delivery_unknown webhook.test unknown
  • statusstring
    pending ждет отправки, delivering отправляется, succeeded доставлено, failed не доставлено, cancelled отменено. Значения: pending delivering succeeded failed cancelled unknown
  • cancel_reasonstring или null
    Почему доставка отменена: scope_changed, endpoint_deleted, expired, other. У неотмененной null. Значения: scope_changed endpoint_deleted expired other
  • attemptinteger
    Сколько было попыток.
  • next_attempt_atstring (date-time) или null
    Когда следующая попытка. Только у pending, иначе null.
  • last_status_codeinteger или null
    Код ответа получателя на последнюю попытку или null.
  • last_error_classstring или null
    Класс ошибки последней попытки или null. Значения: invalid_url dns ssrf_blocked connect tls timeout http payload_too_large unknown
  • last_duration_msinteger или null
    Длительность последней попытки в миллисекундах или null.
  • created_atstring (date-time)
    Когда событие поставлено на доставку.
  • finished_atstring (date-time) или null
    Когда доставка закончилась или null.
WebhookDelivery
{
  "object": "webhook_delivery",
  "id": "7c4e1a85-2d9b-4f63-a0e8-5b3f9c7d2e16",
  "endpoint_id": "6b2d9f40-3c1e-4a7b-8f5d-2e9c0a1b7d64",
  "event_id": "evt_1f8a3c5e7b9d4a2c6e0f8b1d3a5c7e9f",
  "event_type": "lead.replied",
  "status": "succeeded",
  "cancel_reason": null,
  "attempt": 1,
  "next_attempt_at": null,
  "last_status_code": 200,
  "last_error_class": null,
  "last_duration_ms": 184,
  "created_at": "2026-10-27T09:15:02.000Z",
  "finished_at": "2026-10-27T09:15:03.000Z"
}

#Список адресов вебхуков

GET/v1/webhook-endpoints

Адреса вебхуков кабинета и их состояние: принимают ли события, с какого момента ошибки, последняя ошибка и доставки за сутки, от старых к новым. Нужен ключ на все пространства и кампании: вебхуки общие для кабинета.

Право
webhooks:read
Вес запроса
1

Параметры

  • limitinteger, в строке запросанеобязательный
    Сколько объектов вернуть на странице. От 1 до 100. По умолчанию 50.
  • cursorstring, в строке запросанеобязательный
    Значение next_cursor из предыдущего ответа. Остальные фильтры должны совпадать с первым запросом.
  • statusstring, в строке запросанеобязательный
    Только адреса в этом состоянии. Значения: active paused disabled

Ответ

Список: object, data (массив объектов WebhookEndpoint), has_more, next_cursor. Подробнее в руководстве Пагинация.

Особые ошибки

  • cursor_mismatch: Курсор поврежден, выдан для другого маршрута или фильтров, либо права и охват ключа изменились.
  • scope_required: Ключ не разрешает операцию. Для команды нужно право ее вида.
  • not_found: Объект не найден или находится вне охвата ключа. Неизвестный путь тоже дает 404.
  • cursor_expired: Срок курсора истек: 15 минут для списков, 30 суток для ленты событий.

Общие ошибки описаны в руководстве Ошибки.

Запрос
curl https://api.melioralab.io/v1/webhook-endpoints \
  -H "Authorization: Bearer $MELIORA_API_KEY"
Ответ
{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "6b2d9f40-3c1e-4a7b-8f5d-2e9c0a1b7d64",
      "status": "active",
      "disabled_reason": null,
      "host": "hooks.example.com",
      "description": "CRM",
      "event_types": [
        "lead.first_message_sent",
        "lead.replied"
      ],
      "workspace_ids": null,
      "campaign_ids": null,
      "include_message_text": false,
      "header_names": [
        "x-api-key"
      ],
      "failing_since": null,
      "consecutive_failures": 0,
      "last_success_at": "2026-10-27T09:15:03.000Z",
      "version": 2,
      "created_at": "2026-10-20T08:00:00.000Z",
      "updated_at": "2026-10-22T12:30:00.000Z",
      "deliveries": {
        "pending": 0,
        "succeeded_24h": 38,
        "failed_24h": 0,
        "last_finished_at": "2026-10-27T09:15:03.000Z",
        "last_status_code": 200,
        "last_error_class": null
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

#Получить адрес вебхука

GET/v1/webhook-endpoints/{id}

Один адрес вебхука по идентификатору. Удаленный адрес дает 404.

Право
webhooks:read
Вес запроса
1

Параметры

  • idstring (uuid), в путиобязательный
    Идентификатор адреса вебхука.

Ответ

Объект WebhookEndpoint.

Особые ошибки

  • scope_required: Ключ не разрешает операцию. Для команды нужно право ее вида.
  • not_found: Объект не найден или находится вне охвата ключа. Неизвестный путь тоже дает 404.

Общие ошибки описаны в руководстве Ошибки.

Запрос
curl https://api.melioralab.io/v1/webhook-endpoints/ \
  -H "Authorization: Bearer $MELIORA_API_KEY"
Ответ
{
  "object": "webhook_endpoint",
  "id": "6b2d9f40-3c1e-4a7b-8f5d-2e9c0a1b7d64",
  "status": "active",
  "disabled_reason": null,
  "host": "hooks.example.com",
  "description": "CRM",
  "event_types": [
    "lead.first_message_sent",
    "lead.replied"
  ],
  "workspace_ids": null,
  "campaign_ids": null,
  "include_message_text": false,
  "header_names": [
    "x-api-key"
  ],
  "failing_since": null,
  "consecutive_failures": 0,
  "last_success_at": "2026-10-27T09:15:03.000Z",
  "version": 2,
  "created_at": "2026-10-20T08:00:00.000Z",
  "updated_at": "2026-10-22T12:30:00.000Z",
  "deliveries": {
    "pending": 0,
    "succeeded_24h": 38,
    "failed_24h": 0,
    "last_finished_at": "2026-10-27T09:15:03.000Z",
    "last_status_code": 200,
    "last_error_class": null
  }
}

#Журнал доставок

GET/v1/webhook-endpoints/{id}/deliveries

Доставки событий на один адрес, от новых к старым: состояние, попытки, код ответа и ошибка. Помогает понять, почему CRM не получила событие. Само событие отдает лента событий по event_id.

Право
webhooks:read
Вес запроса
2

Параметры

  • idstring (uuid), в путиобязательный
    Идентификатор адреса вебхука.
  • limitinteger, в строке запросанеобязательный
    Сколько объектов вернуть на странице. От 1 до 100. По умолчанию 50.
  • cursorstring, в строке запросанеобязательный
    Значение next_cursor из предыдущего ответа. Остальные фильтры должны совпадать с первым запросом.
  • statusstring, в строке запросанеобязательный
    Только доставки в этом состоянии. Значения: pending delivering succeeded failed cancelled

Ответ

Список: object, data (массив объектов WebhookDelivery), has_more, next_cursor. Подробнее в руководстве Пагинация.

Особые ошибки

  • cursor_mismatch: Курсор поврежден, выдан для другого маршрута или фильтров, либо права и охват ключа изменились.
  • scope_required: Ключ не разрешает операцию. Для команды нужно право ее вида.
  • not_found: Объект не найден или находится вне охвата ключа. Неизвестный путь тоже дает 404.
  • cursor_expired: Срок курсора истек: 15 минут для списков, 30 суток для ленты событий.

Общие ошибки описаны в руководстве Ошибки.

Запрос
curl https://api.melioralab.io/v1/webhook-endpoints//deliveries \
  -H "Authorization: Bearer $MELIORA_API_KEY"
Ответ
{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": "7c4e1a85-2d9b-4f63-a0e8-5b3f9c7d2e16",
      "endpoint_id": "6b2d9f40-3c1e-4a7b-8f5d-2e9c0a1b7d64",
      "event_id": "evt_1f8a3c5e7b9d4a2c6e0f8b1d3a5c7e9f",
      "event_type": "lead.replied",
      "status": "succeeded",
      "cancel_reason": null,
      "attempt": 1,
      "next_attempt_at": null,
      "last_status_code": 200,
      "last_error_class": null,
      "last_duration_ms": 184,
      "created_at": "2026-10-27T09:15:02.000Z",
      "finished_at": "2026-10-27T09:15:03.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU"
}