Вебхуки

Методы группы «MAX: вебхуки». Справа — пример запроса и ответа для каждого.

Список вебхуков

GET/v1/max/webhooks/

0 единицс тарифа «API.Max Рост»

Все вебхуки организации ключа: адрес, каналы, включён ли, сколько доставок ждут, последняя успешная доставка и последняя ошибка. Секретов подписи в ответе нет. С тарифа «API.Max Рост», 0 единиц.

Поля ответа

Поле	Тип	Описание
`results`	список	Вебхуки организации ключа
`results[].id`	число	Номер вебхука — в адресах /v1/max/webhooks/{id}/ и в событиях
`results[].url`	строка	Адрес, на который приходят события (https://)
`results[].is_active`	да / нет	Включён ли вебхук
`results[].disabled_reason`	строка	Почему выключен: failing — сутки без успешной доставки, client — выключен вами, staff — сотрудником datool.ru; пусто — включён
`results[].channels`	список	Номера подписанных каналов MAX
`results[].pending`	число	Доставок ждут отправки
`results[].created_at`	дата и время	Когда вебхук создан (ISO 8601, по Москве)
`results[].last_success_at`	дата и время или null	Последняя успешная доставка
`results[].failing_since`	дата и время или null	С какого момента нет успешных доставок; null — всё хорошо
`results[].last_error`	строка	Последняя ошибка доставки коротко

Ошибки

Код	code	Когда
401	`not_authenticated / authentication_failed`	Нет ключа, ключ неверный или отозван, участник приостановлен или организация ключа в архиве.
403	`tariff_required`	Вебхуки открыты с тарифа «API.Max Рост».
429	`rate_limited / throttled`	Слишком часто — больше запросов в секунду, чем по тарифу; сколько ждать — в заголовке Retry-After.

Список вебхуков

Пример запроса:

# библиотека для HTTP-запросов: pip install requests
import requests

# адрес метода
URL = "https://api.datool.ru/v1/max/webhooks/"
# ключ API из кабинета hi.datool.ru — замените на свой
HEADERS = {"Authorization": "Bearer dtk_…"}

# выполнить запрос
response = requests.get(URL, headers=HEADERS, timeout=30)
# ответ — JSON
print(response.status_code, response.json())

# ключ API из кабинета hi.datool.ru — замените на свой
curl "https://api.datool.ru/v1/max/webhooks/" \
  -H "Authorization: Bearer dtk_…"

Ответ 200:

{
  "results": [
    {
      "id": 12,
      "url": "https://example.com/hooks/datool",
      "is_active": true,
      "disabled_reason": "",
      "channels": [
        4821,
        5310
      ],
      "pending": 0,
      "created_at": "2026-10-18T12:00:00+03:00",
      "last_success_at": "2026-10-18T12:12:05+03:00",
      "failing_since": null,
      "last_error": ""
    }
  ]
}

Создать вебхук

POST/v1/max/webhooks/

0 единицс тарифа «API.Max Рост», ключ «чтение и запись»

Новый вебхук: события post.created о новых постах этих каналов будут приходить POST-запросом на адрес. Секрет подписи — в ответе, показывается один раз.

Тело запроса

JSON с заголовком Content-Type: application/json.

Поле	Тип	Описание
`url`	строка	Адрес https://, на который приходят события
`channels`	список	Номера открытых каналов MAX в datool.ru (поле id в каталоге)

Поля ответа

Поле	Тип	Описание
`id`	число	Номер вебхука — в адресах /v1/max/webhooks/{id}/ и в событиях
`url`	строка	Адрес, на который приходят события (https://)
`is_active`	да / нет	Включён ли вебхук
`disabled_reason`	строка	Почему выключен: failing — сутки без успешной доставки, client — выключен вами, staff — сотрудником datool.ru; пусто — включён
`channels`	список	Номера подписанных каналов MAX
`pending`	число	Доставок ждут отправки
`created_at`	дата и время	Когда вебхук создан (ISO 8601, по Москве)
`last_success_at`	дата и время или null	Последняя успешная доставка
`failing_since`	дата и время или null	С какого момента нет успешных доставок; null — всё хорошо
`last_error`	строка	Последняя ошибка доставки коротко
`secret`	строка	Секрет подписи X-Datool-Signature. Показывается один раз — сохраните его

Ошибки

Код	code	Когда
400	ошибки полей	Неверный параметр или поле тела: ошибка приходит у имени поля, например {"channels": ["Номера каналов через запятую."]}.
401	`not_authenticated / authentication_failed`	Нет ключа, ключ неверный или отозван, участник приостановлен или организация ключа в архиве.
403	`tariff_required`	Вебхуки открыты с тарифа «API.Max Рост».
403	`read_only_key`	Ключ без отметки «чтение и запись».
403	`manager_required`	Ключ участника: менять вебхуки может владелец или администратор.
403	`limit_reached`	Вебхуков уже столько, сколько разрешает тариф.
429	`rate_limited / throttled`	Слишком часто — больше запросов в секунду, чем по тарифу; сколько ждать — в заголовке Retry-After.
503	`timeout`	Запрос к базе не уложился в 5 секунд — повторите позже или сузьте выборку.

Создать вебхук

Пример запроса:

# библиотека для HTTP-запросов: pip install requests
import requests

# адрес метода
URL = "https://api.datool.ru/v1/max/webhooks/"
# ключ API из кабинета hi.datool.ru — замените на свой
HEADERS = {"Authorization": "Bearer dtk_…"}
# тело запроса — JSON
BODY = {"url": "https://example.com/hooks/datool", "channels": [4821, 5310]}

# выполнить запрос
response = requests.post(URL, headers=HEADERS, json=BODY, timeout=30)
# ответ — JSON
print(response.status_code, response.json())

# ключ API из кабинета hi.datool.ru — замените на свой
# тело запроса — JSON
curl -X POST "https://api.datool.ru/v1/max/webhooks/" \
  -H "Authorization: Bearer dtk_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/datool", "channels": [4821, 5310]}'

Ответ 201:

{
  "id": 12,
  "url": "https://example.com/hooks/datool",
  "is_active": true,
  "disabled_reason": "",
  "channels": [
    4821,
    5310
  ],
  "pending": 0,
  "created_at": "2026-10-18T12:00:00+03:00",
  "last_success_at": "2026-10-18T12:12:05+03:00",
  "failing_since": null,
  "last_error": "",
  "secret": "whsec_Vq3kP0b8…"
}

Вебхук

GET/v1/max/webhooks/{id}/

0 единицс тарифа «API.Max Рост»

Один вебхук организации: каналы, состояние, сколько доставок ждут отправки, последняя успешная доставка и ошибка. Вебхук другой организации — 404.

Параметры

Имя параметра	Где	Описание
`id` обязателен число	путь	Номер вебхука

Поля ответа

Поле	Тип	Описание
`id`	число	Номер вебхука — в адресах /v1/max/webhooks/{id}/ и в событиях
`url`	строка	Адрес, на который приходят события (https://)
`is_active`	да / нет	Включён ли вебхук
`disabled_reason`	строка	Почему выключен: failing — сутки без успешной доставки, client — выключен вами, staff — сотрудником datool.ru; пусто — включён
`channels`	список	Номера подписанных каналов MAX
`pending`	число	Доставок ждут отправки
`created_at`	дата и время	Когда вебхук создан (ISO 8601, по Москве)
`last_success_at`	дата и время или null	Последняя успешная доставка
`failing_since`	дата и время или null	С какого момента нет успешных доставок; null — всё хорошо
`last_error`	строка	Последняя ошибка доставки коротко

Ошибки

Код	code	Когда
401	`not_authenticated / authentication_failed`	Нет ключа, ключ неверный или отозван, участник приостановлен или организация ключа в архиве.
403	`tariff_required`	Вебхуки открыты с тарифа «API.Max Рост».
404	`not_found`	Нет объекта с таким номером или именем, или он вам не виден.
429	`rate_limited / throttled`	Слишком часто — больше запросов в секунду, чем по тарифу; сколько ждать — в заголовке Retry-After.

Вебхук

Пример запроса:

# библиотека для HTTP-запросов: pip install requests
import requests

# адрес метода
URL = "https://api.datool.ru/v1/max/webhooks/12/"
# ключ API из кабинета hi.datool.ru — замените на свой
HEADERS = {"Authorization": "Bearer dtk_…"}

# выполнить запрос
response = requests.get(URL, headers=HEADERS, timeout=30)
# ответ — JSON
print(response.status_code, response.json())

# ключ API из кабинета hi.datool.ru — замените на свой
curl "https://api.datool.ru/v1/max/webhooks/12/" \
  -H "Authorization: Bearer dtk_…"

Ответ 200:

{
  "id": 12,
  "url": "https://example.com/hooks/datool",
  "is_active": true,
  "disabled_reason": "",
  "channels": [
    4821,
    5310
  ],
  "pending": 0,
  "created_at": "2026-10-18T12:00:00+03:00",
  "last_success_at": "2026-10-18T12:12:05+03:00",
  "failing_since": null,
  "last_error": ""
}

Изменить вебхук

PATCH/v1/max/webhooks/{id}/

0 единицс тарифа «API.Max Рост», ключ «чтение и запись»

Любые из полей: адрес, список каналов (заменяет прежний целиком), is_active. is_active=true включает выключенный вебхук: ошибки забываются, посты пойдут с текущего момента. Вебхук, выключенный сотрудником datool.ru (disabled_reason=staff), так не включить — 409 conflict, напишите в поддержку.

Параметры

Имя параметра	Где	Описание
`id` обязателен число	путь	Номер вебхука

Тело запроса

JSON с заголовком Content-Type: application/json.

Поле	Тип	Описание
`url`	строка	Новый адрес
`channels`	список	Новый список каналов — заменяет прежний целиком
`is_active`	да / нет	true — включить снова (ошибки забываются), false — выключить

Поля ответа

Поле	Тип	Описание
`id`	число	Номер вебхука — в адресах /v1/max/webhooks/{id}/ и в событиях
`url`	строка	Адрес, на который приходят события (https://)
`is_active`	да / нет	Включён ли вебхук
`disabled_reason`	строка	Почему выключен: failing — сутки без успешной доставки, client — выключен вами, staff — сотрудником datool.ru; пусто — включён
`channels`	список	Номера подписанных каналов MAX
`pending`	число	Доставок ждут отправки
`created_at`	дата и время	Когда вебхук создан (ISO 8601, по Москве)
`last_success_at`	дата и время или null	Последняя успешная доставка
`failing_since`	дата и время или null	С какого момента нет успешных доставок; null — всё хорошо
`last_error`	строка	Последняя ошибка доставки коротко

Ошибки

Код	code	Когда
400	ошибки полей	Неверный параметр или поле тела: ошибка приходит у имени поля, например {"channels": ["Номера каналов через запятую."]}.
401	`not_authenticated / authentication_failed`	Нет ключа, ключ неверный или отозван, участник приостановлен или организация ключа в архиве.
403	`tariff_required`	Вебхуки открыты с тарифа «API.Max Рост».
403	`read_only_key`	Ключ без отметки «чтение и запись».
403	`manager_required`	Ключ участника: менять вебхуки может владелец или администратор.
404	`not_found`	Нет объекта с таким номером или именем, или он вам не виден.
409	`conflict`	Вебхук выключен сотрудником datool.ru — включить его может только поддержка.
429	`rate_limited / throttled`	Слишком часто — больше запросов в секунду, чем по тарифу; сколько ждать — в заголовке Retry-After.
503	`timeout`	Запрос к базе не уложился в 5 секунд — повторите позже или сузьте выборку.

Изменить вебхук

Пример запроса:

# библиотека для HTTP-запросов: pip install requests
import requests

# адрес метода
URL = "https://api.datool.ru/v1/max/webhooks/12/"
# ключ API из кабинета hi.datool.ru — замените на свой
HEADERS = {"Authorization": "Bearer dtk_…"}
# тело запроса — JSON
BODY = {"url": "https://example.com/hooks/datool", "channels": [4821, 5310], "is_active": True}

# выполнить запрос
response = requests.patch(URL, headers=HEADERS, json=BODY, timeout=30)
# ответ — JSON
print(response.status_code, response.json())

# ключ API из кабинета hi.datool.ru — замените на свой
# тело запроса — JSON
curl -X PATCH "https://api.datool.ru/v1/max/webhooks/12/" \
  -H "Authorization: Bearer dtk_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/datool", "channels": [4821, 5310], "is_active": true}'

Ответ 200:

{
  "id": 12,
  "url": "https://example.com/hooks/datool",
  "is_active": true,
  "disabled_reason": "",
  "channels": [
    4821,
    5310
  ],
  "pending": 0,
  "created_at": "2026-10-18T12:00:00+03:00",
  "last_success_at": "2026-10-18T12:12:05+03:00",
  "failing_since": null,
  "last_error": ""
}

Удалить вебхук

DELETE/v1/max/webhooks/{id}/

0 единицс тарифа «API.Max Рост», ключ «чтение и запись»

Удалить вебхук вместе с очередью ещё не отправленных доставок. Нужен ключ с отметкой «чтение и запись». Ответ 204 без тела.

Параметры

Имя параметра	Где	Описание
`id` обязателен число	путь	Номер вебхука

Ошибки

Код	code	Когда
401	`not_authenticated / authentication_failed`	Нет ключа, ключ неверный или отозван, участник приостановлен или организация ключа в архиве.
403	`tariff_required`	Вебхуки открыты с тарифа «API.Max Рост».
403	`read_only_key`	Ключ без отметки «чтение и запись».
403	`manager_required`	Ключ участника: менять вебхуки может владелец или администратор.
404	`not_found`	Нет объекта с таким номером или именем, или он вам не виден.
429	`rate_limited / throttled`	Слишком часто — больше запросов в секунду, чем по тарифу; сколько ждать — в заголовке Retry-After.

Удалить вебхук

Пример запроса:

# библиотека для HTTP-запросов: pip install requests
import requests

# адрес метода
URL = "https://api.datool.ru/v1/max/webhooks/12/"
# ключ API из кабинета hi.datool.ru — замените на свой
HEADERS = {"Authorization": "Bearer dtk_…"}

# выполнить запрос
response = requests.delete(URL, headers=HEADERS, timeout=30)
# ответ 204 — без тела
print(response.status_code)

# ключ API из кабинета hi.datool.ru — замените на свой
curl -X DELETE "https://api.datool.ru/v1/max/webhooks/12/" \
  -H "Authorization: Bearer dtk_…"

Ответ 204:

Без тела ответа

Сменить секрет подписи

POST/v1/max/webhooks/{id}/rotate-secret/

0 единицс тарифа «API.Max Рост», ключ «чтение и запись»

Новый секрет подписи: прежний перестаёт действовать сразу. Секрет — в ответе, показывается один раз.

Параметры

Имя параметра	Где	Описание
`id` обязателен число	путь	Номер вебхука

Поля ответа

Поле	Тип	Описание
`id`	число	Номер вебхука — в адресах /v1/max/webhooks/{id}/ и в событиях
`url`	строка	Адрес, на который приходят события (https://)
`is_active`	да / нет	Включён ли вебхук
`disabled_reason`	строка	Почему выключен: failing — сутки без успешной доставки, client — выключен вами, staff — сотрудником datool.ru; пусто — включён
`channels`	список	Номера подписанных каналов MAX
`pending`	число	Доставок ждут отправки
`created_at`	дата и время	Когда вебхук создан (ISO 8601, по Москве)
`last_success_at`	дата и время или null	Последняя успешная доставка
`failing_since`	дата и время или null	С какого момента нет успешных доставок; null — всё хорошо
`last_error`	строка	Последняя ошибка доставки коротко
`secret`	строка	Секрет подписи X-Datool-Signature. Показывается один раз — сохраните его

Ошибки

Код	code	Когда
401	`not_authenticated / authentication_failed`	Нет ключа, ключ неверный или отозван, участник приостановлен или организация ключа в архиве.
403	`tariff_required`	Вебхуки открыты с тарифа «API.Max Рост».
403	`read_only_key`	Ключ без отметки «чтение и запись».
403	`manager_required`	Ключ участника: менять вебхуки может владелец или администратор.
404	`not_found`	Нет объекта с таким номером или именем, или он вам не виден.
429	`rate_limited / throttled`	Слишком часто — больше запросов в секунду, чем по тарифу; сколько ждать — в заголовке Retry-After.

Сменить секрет подписи

Пример запроса:

# библиотека для HTTP-запросов: pip install requests
import requests

# адрес метода
URL = "https://api.datool.ru/v1/max/webhooks/12/rotate-secret/"
# ключ API из кабинета hi.datool.ru — замените на свой
HEADERS = {"Authorization": "Bearer dtk_…"}

# выполнить запрос
response = requests.post(URL, headers=HEADERS, timeout=30)
# ответ — JSON
print(response.status_code, response.json())

# ключ API из кабинета hi.datool.ru — замените на свой
curl -X POST "https://api.datool.ru/v1/max/webhooks/12/rotate-secret/" \
  -H "Authorization: Bearer dtk_…"

Ответ 200:

{
  "id": 12,
  "url": "https://example.com/hooks/datool",
  "is_active": true,
  "disabled_reason": "",
  "channels": [
    4821,
    5310
  ],
  "pending": 0,
  "created_at": "2026-10-18T12:00:00+03:00",
  "last_success_at": "2026-10-18T12:12:05+03:00",
  "failing_since": null,
  "last_error": "",
  "secret": "whsec_Vq3kP0b8…"
}

Проверить вебхук

POST/v1/max/webhooks/{id}/test/

0 единицс тарифа «API.Max Рост», ключ «чтение и запись»

Пробная доставка события ping без постов — проверить адрес и подпись. Одна попытка, без повторов; не чаще раза в минуту на вебхук (чаще — 429 throttled с заголовком Retry-After). Итог виден в полях last_success_at и last_error через несколько секунд.

Параметры

Имя параметра	Где	Описание
`id` обязателен число	путь	Номер вебхука

Поля ответа

Поле	Тип	Описание
`delivery`	число	Номер доставки (заголовок X-Datool-Delivery)
`status`	строка	queued — поставлена в очередь отправки

Ошибки

Код	code	Когда
401	`not_authenticated / authentication_failed`	Нет ключа, ключ неверный или отозван, участник приостановлен или организация ключа в архиве.
403	`tariff_required`	Вебхуки открыты с тарифа «API.Max Рост».
403	`read_only_key`	Ключ без отметки «чтение и запись».
403	`manager_required`	Ключ участника: менять вебхуки может владелец или администратор.
404	`not_found`	Нет объекта с таким номером или именем, или он вам не виден.
409	`conflict`	Вебхук выключен — включите его (is_active=true) и повторите.
429	`throttled`	Проверять вебхук можно не чаще раза в минуту.
429	`rate_limited / throttled`	Слишком часто — больше запросов в секунду, чем по тарифу; сколько ждать — в заголовке Retry-After.

Проверить вебхук

Пример запроса:

# библиотека для HTTP-запросов: pip install requests
import requests

# адрес метода
URL = "https://api.datool.ru/v1/max/webhooks/12/test/"
# ключ API из кабинета hi.datool.ru — замените на свой
HEADERS = {"Authorization": "Bearer dtk_…"}

# выполнить запрос
response = requests.post(URL, headers=HEADERS, timeout=30)
# ответ — JSON
print(response.status_code, response.json())

# ключ API из кабинета hi.datool.ru — замените на свой
curl -X POST "https://api.datool.ru/v1/max/webhooks/12/test/" \
  -H "Authorization: Bearer dtk_…"

Ответ 202:

{
  "delivery": 3456,
  "status": "queued"
}

Формат ошибок, заголовки лимитов и что делать при каждой — в статье «Ошибки».