Справочник · Вебхуки

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

Адреса вебхуков: сюда Dialogi присылает события - новый диалог, сообщение, контакт, заявку, запись. Адресов у компании не больше 10. Подписаться можно только на события тех ресурсов, которые ключ может читать, и только на проекты ключа. Как проверять подпись запроса - в разделе Вебхуки.

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

Адрес вебхуков - URL, на который Dialogi присылает события.

objectстрокаобязателен

Тип объекта, всегда webhook_endpoint.

Значения: webhook_endpoint

iduuidобязателен

id адреса.

urlссылкаобязателен

Адрес, на который приходят события. Домен с кириллицей хранится в виде xn--.

descriptionстрокаобязателенможет быть null

Описание для себя.

enabled_eventsмассив (строка)обязателен

Типы событий, на которые подписан адрес, или ["*"] - все события, в том числе будущие. См. События.

project_idsмассив (uuid)обязателенможет быть null

id проектов, события которых приходят на адрес. null - все проекты компании. Пустой список бывает у адреса, все проекты которого удалили: такой адрес выключен.

statusстрокаобязателен

enabled - события отправляются, disabled - адрес выключен.

disabled_reasonстрокаобязателенможет быть null

Почему адрес выключен: manual - выключили вручную или удалили все его проекты, failing - адрес не отвечал 2xx 72 часа. У включённого адреса - null.

disabled_atдата и время с зонойобязателенможет быть null

Когда адрес выключили, UTC. У включённого - null.

created_atдата и время с зонойобязателен

Когда адрес создан, UTC.

updated_atдата и время с зонойобязателен

Когда адрес последний раз меняли, UTC.

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

{
  "object": "webhook_endpoint",
  "id": "01a0e2b4-6c1d-7f3a-9b2e-4d5c6a7b8e90",
  "url": "https://example.com/dialogi/webhooks",
  "description": "Заявки в 1С",
  "enabled_events": [
    "lead.created",
    "lead.updated"
  ],
  "project_ids": [
    "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "disabled_at": null,
  "created_at": "2026-09-28T09:41:12Z",
  "updated_at": "2026-09-28T09:41:12Z"
}

GET/v1/webhook_endpoints

Список адресов

Право: webhooks:manage

Адреса вебхуков компании, от новых к старым. Ключ видит только адреса своих проектов.

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

limitцелое числоможет быть null

Сколько адресов на странице, от 1 до 100.

По умолчанию: 20

starting_afteruuidможет быть null

id последнего адреса предыдущей страницы: страница начнётся после него. См. Пагинация.

Ответы

200Страница списка адресов.
401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
402У компании не подключено дополнение «Публичный API» (api-addon-required).
403У ключа нет нужного права или доступа к проекту (forbidden).
422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
503Сервис временно недоступен (unavailable). Повторите позже.

Запрос

curl https://api.ru.dialogi.io/v1/webhook_endpoints \
  -H "Authorization: Bearer dk_live_…"

Ответ 200

{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "01a0e2b4-6c1d-7f3a-9b2e-4d5c6a7b8e90",
      "url": "https://example.com/dialogi/webhooks",
      "description": "Заявки в 1С",
      "enabled_events": [
        "lead.created",
        "lead.updated"
      ],
      "project_ids": [
        "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20"
      ],
      "status": "enabled",
      "disabled_reason": null,
      "disabled_at": null,
      "created_at": "2026-09-28T09:41:12Z",
      "updated_at": "2026-09-28T09:41:12Z"
    }
  ],
  "has_more": true
}

POST/v1/webhook_endpoints

Создать адрес

Право: webhooks:manage Idempotency-Key обязателен

Создаёт адрес и сразу начинает слать на него события. Адрес - только https с публичным сертификатом, порт 443 или от 1024 до 65535. Секрет для проверки подписи приходит в ответе один раз - сохраните его.

Каждое событие нужно ключу на чтение: conversation.* и message.* - право conversations:read, contact.* - contacts:read, lead.* - leads:read, appointment.* - appointments:read. * требует все четыре права. Если права нет - ошибка 403 с перечнем событий.

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

urlстрокаобязателен

Адрес, на который придут события: https, без логина и пароля в адресе.

descriptionстрокаможет быть null

Описание для себя, до 256 символов.

enabled_eventsмассив (строка)обязателен

Типы событий, например lead.created, или ["*"] - все события, в том числе будущие. Список типов - в разделе События.

project_idsмассив (строка)может быть null

id проектов, события которых слать. null или без поля - все проекты компании, так может только ключ на все проекты.

Ответы

201Созданный адрес с секретом.
400Нет заголовка Idempotency-Key (idempotency-key-required) или ключ в неверном формате (idempotency-key-invalid).
401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
402У компании не подключено дополнение «Публичный API» (api-addon-required).
403У ключа нет нужного права или доступа к проекту (forbidden). У ключа нет права на чтение части событий (в detail - их перечень) или проекты адреса шире проектов ключа.
409Idempotency-Key уже использован с другим запросом (idempotency-conflict) или первый запрос с ним ещё выполняется (idempotency-in-progress). У компании уже 10 адресов (webhook-endpoint-limit).
422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
503Сервис временно недоступен (unavailable). Повторите позже.

Запрос

curl https://api.ru.dialogi.io/v1/webhook_endpoints \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20195208" \
  -d '{
    "url": "https://example.com/dialogi/webhooks",
    "enabled_events": [
      "lead.created",
      "lead.updated"
    ]
  }'

Ответ 201

{
  "object": "webhook_endpoint",
  "id": "01a0e2b4-6c1d-7f3a-9b2e-4d5c6a7b8e90",
  "url": "https://example.com/dialogi/webhooks",
  "description": "Заявки в 1С",
  "enabled_events": [
    "lead.created",
    "lead.updated"
  ],
  "project_ids": [
    "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "disabled_at": null,
  "created_at": "2026-09-28T09:41:12Z",
  "updated_at": "2026-09-28T09:41:12Z",
  "secret": "whsec_2cGx4kYp9QmT7vR1nB5sW8dF3hJ6zL0a"
}

GET/v1/webhook_endpoints/{endpoint}

Получить адрес

Право: webhooks:manage

Адрес по id. Адрес с проектами, которых нет в ключе, для ключа не существует - ответ 404.

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

endpointuuidобязателен

id адреса.

Ответы

200Адрес.
401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
402У компании не подключено дополнение «Публичный API» (api-addon-required).
403У ключа нет нужного права или доступа к проекту (forbidden).
404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
503Сервис временно недоступен (unavailable). Повторите позже.

Запрос

curl https://api.ru.dialogi.io/v1/webhook_endpoints/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90 \
  -H "Authorization: Bearer dk_live_…"

Ответ 200

{
  "object": "webhook_endpoint",
  "id": "01a0e2b4-6c1d-7f3a-9b2e-4d5c6a7b8e90",
  "url": "https://example.com/dialogi/webhooks",
  "description": "Заявки в 1С",
  "enabled_events": [
    "lead.created",
    "lead.updated"
  ],
  "project_ids": [
    "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "disabled_at": null,
  "created_at": "2026-09-28T09:41:12Z",
  "updated_at": "2026-09-28T09:41:12Z"
}

PATCH/v1/webhook_endpoints/{endpoint}

Изменить адрес

Право: webhooks:manage

Меняет только переданные поля. status: enabled включает адрес после ручного или автоматического отключения: события, пропущенные за время отключения, не досылаются. Права ключа проверяются по событиям адреса после изменения, даже если enabled_events не передан.

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

endpointuuidобязателен

id адреса.

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

urlстрока

Адрес, на который придут события: https, без логина и пароля в адресе.

descriptionстрокаможет быть null

Описание для себя, до 256 символов. null очищает его.

enabled_eventsмассив (строка)

Типы событий или ["*"] - все события.

project_idsмассив (строка)может быть null

id проектов или null - все проекты компании (только у ключа на все проекты).

statusстрока

enabled - включить, disabled - выключить.

Значения: enableddisabled

Ответы

200Адрес после изменения.
401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
402У компании не подключено дополнение «Публичный API» (api-addon-required).
403У ключа нет нужного права или доступа к проекту (forbidden). У ключа нет права на чтение части событий адреса (в detail - их перечень) или проекты адреса шире проектов ключа.
404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
503Сервис временно недоступен (unavailable). Повторите позже.

Запрос

curl -X PATCH https://api.ru.dialogi.io/v1/webhook_endpoints/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90 \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "enabled"
  }'

Ответ 200

{
  "object": "webhook_endpoint",
  "id": "01a0e2b4-6c1d-7f3a-9b2e-4d5c6a7b8e90",
  "url": "https://example.com/dialogi/webhooks",
  "description": "Заявки в 1С",
  "enabled_events": [
    "lead.created",
    "lead.updated"
  ],
  "project_ids": [
    "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "disabled_at": null,
  "created_at": "2026-09-28T09:41:12Z",
  "updated_at": "2026-09-28T09:41:12Z"
}

DELETE/v1/webhook_endpoints/{endpoint}

Удалить адрес

Право: webhooks:manage

Удаляет адрес: события на него больше не отправляются, ожидающие повторы отменяются.

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

endpointuuidобязателен

id адреса.

Ответы

200Адрес удалён.
401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
402У компании не подключено дополнение «Публичный API» (api-addon-required).
403У ключа нет нужного права или доступа к проекту (forbidden).
404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
503Сервис временно недоступен (unavailable). Повторите позже.

Запрос

curl -X DELETE https://api.ru.dialogi.io/v1/webhook_endpoints/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90 \
  -H "Authorization: Bearer dk_live_…"

Ответ 200

{
  "object": "webhook_endpoint",
  "id": "01a0e2b4-6c1d-7f3a-9b2e-4d5c6a7b8e90",
  "deleted": true
}

POST/v1/webhook_endpoints/{endpoint}/roll_secret

Перевыпустить секрет

Право: webhooks:manage Idempotency-Key поддерживается

Выдаёт новый секрет, он приходит в ответе один раз. Старый секрет ещё expires_in_hours часов подписывает запросы вместе с новым: в заголовке Dialogi-Signature будет по одной подписи v1 на каждый.

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

endpointuuidобязателен

id адреса.

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

expires_in_hoursцелое числообязателен

Сколько часов старый секрет ещё действует: 0 - перестаёт сразу, 1 или 24.

Значения: 0124

Ответы

200Адрес с новым секретом.
400Idempotency-Key в неверном формате (idempotency-key-invalid).
401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
402У компании не подключено дополнение «Публичный API» (api-addon-required).
403У ключа нет нужного права или доступа к проекту (forbidden).
404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
409Idempotency-Key уже использован с другим запросом (idempotency-conflict) или первый запрос с ним ещё выполняется (idempotency-in-progress).
422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After.
503Сервис временно недоступен (unavailable). Повторите позже.

Запрос

curl https://api.ru.dialogi.io/v1/webhook_endpoints/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90/roll_secret \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20195208" \
  -d '{
    "expires_in_hours": "0"
  }'

Ответ 200

{
  "object": "webhook_endpoint",
  "id": "01a0e2b4-6c1d-7f3a-9b2e-4d5c6a7b8e90",
  "url": "https://example.com/dialogi/webhooks",
  "description": "Заявки в 1С",
  "enabled_events": [
    "lead.created",
    "lead.updated"
  ],
  "project_ids": [
    "01a0c4e2-3f10-7b4d-9c2e-5d8a1f6b3e20"
  ],
  "status": "enabled",
  "disabled_reason": null,
  "disabled_at": null,
  "created_at": "2026-09-28T09:41:12Z",
  "updated_at": "2026-09-28T09:41:12Z",
  "secret": "whsec_2cGx4kYp9QmT7vR1nB5sW8dF3hJ6zL0a"
}

POST/v1/webhook_endpoints/{endpoint}/test

Отправить тестовое событие

Право: webhooks:manage Idempotency-Key поддерживается

Сразу отправляет на адрес событие выбранного типа с test: true и образцом объекта с нулевыми id. Ответ приходит после попытки: код ответа вашего сервера, время и ошибка. Повторов у тестового события нет, в список событий оно не попадает. Тест можно отправить и на выключенный адрес.

Не больше одного теста одновременно и 10 в минуту на компанию. Ваш сервер должен ответить за 5 секунд.

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

endpointuuidобязателен

id адреса.

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

typeстрокаобязателен

Тип события, например lead.created.

Ответы

200Итог тестовой отправки.
400Idempotency-Key в неверном формате (idempotency-key-invalid).
401Нет ключа, ключ неверный, истёк или отозван (unauthenticated).
402У компании не подключено дополнение «Публичный API» (api-addon-required).
403У ключа нет нужного права или доступа к проекту (forbidden). У ключа нет права на чтение событий этого типа.
404Объекта с таким id нет или он в проекте, которого нет в ключе (not-found).
409Idempotency-Key уже использован с другим запросом (idempotency-conflict) или первый запрос с ним ещё выполняется (idempotency-in-progress). У компании уже идёт тестовая отправка (webhook-test-in-progress).
422Данные запроса не прошли проверку (validation). Какие поля и почему - в errors.
429Превышен лимит запросов (rate-limited). Повторите через столько секунд, сколько указано в Retry-After. У тестовых событий свой лимит - 10 в минуту на компанию.
503Сервис временно недоступен (unavailable). Повторите позже.

Запрос

curl https://api.ru.dialogi.io/v1/webhook_endpoints/0192d3a1-7b2c-7c3e-9a51-2f6b8e4d1c90/test \
  -H "Authorization: Bearer dk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20195208" \
  -d '{
    "type": "lead.created"
  }'

Ответ 200

{
  "object": "webhook_delivery",
  "id": "01a0e2b5-1a2b-7c3d-8e4f-5a6b7c8d9e01",
  "event_id": "01a0e2b5-19f0-7a1b-8c2d-3e4f5a6b7c8d",
  "status": "failed",
  "status_code": 500,
  "duration_ms": 412,
  "error": "http_500",
  "created_at": "2026-09-28T11:01:30Z"
}