Вебхуки iiko: какие бывают и как начать их получать

Это руководство рассказывает, что такое вебхуки iiko, какие события можно получать и как начать принимать их на своём сервере. В конце на примере события «изменился заказ доставки» разберём, как выглядит входящий запрос.

Руководство рассчитано на начинающих — каждый шаг описан словами и подкреплён командой curl.

Что такое вебхук и зачем он нужен

Обычный запрос к API работает так: вы спрашиваете сервер — сервер отвечает.

Вебхук работает наоборот: сервер сам присылает данные, когда наступает событие.

Например, не нужно постоянно опрашивать iiko «есть ли новый заказ?». Вы один раз настраиваете адрес, и iiko сама присылает POST-запрос каждый раз, когда происходит событие — создаётся или меняется заказ доставки, обновляется стоп-лист и так далее.

Какие события можно получать

Подписавшись на вебхуки, вы можете получать уведомления о событиях:

Тип события	Что означает
`DeliveryOrderUpdate`	Изменение статуса заказа доставки
`DeliveryOrderError`	Ошибка сохранения заказа доставки
`ReserveUpdate`	Изменение резерва
`ReserveError`	Ошибка сохранения резерва
`TableOrderUpdate`	Изменение статуса заказа на стол
`TableOrderError`	Ошибка сохранения заказа на стол
`StopListUpdate`	Обновление стоп-листа
`PersonalShift`	Обновление личной смены сотрудника

Чаще всего для работы с заказами используется тип DeliveryOrderUpdate — именно он сообщает о создании и изменении заказов доставки.

Важно: вебхук StopListUpdate — это лишь уведомление о том, что стоп-лист изменился. Сами позиции в теле вебхука не приходят: после такого события нужно отдельно запросить стоп-лист методом POST /api/1/stop_lists.

Ограничения, которые нужно знать заранее

Для одной организации (organizationId) можно задать только один URL вебхука.
С 04.08.2025 включён механизм блокировки не отвечающих вебхуков. Правила корректной работы и критерии блокировки описаны в статье «Ограничения веб-хуков».

Поэтому ваш сервер должен принимать вебхук и быстро отвечать кодом 200.

Что нужно до начала

Что	Где взять
`appId`, `clientSecret`	Портал разработчика iiko — приложение создаётся в личном кабинете
`apiKey`	iikoWeb → «Интеграции» → «API-ключи»
`organizationId`	Ответ метода `POST /api/1/organizations`
Публичный URL для вебхука	Хостинг, либо `ngrok` для локальной отладки
Токен авторизации (`authToken`)	Любая строка, которую вы придумаете сами (см. ниже)

Токен доступа для запросов получается методом POST /api/v2/access_token:

curl -X POST "https://api-ru.iiko.services/api/v2/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "ВАШ_APP_ID",
    "clientSecret": "ВАШ_CLIENT_SECRET",
    "apiKey": "ВАШ_API_KEY"
  }'

Из ответа возьмите поле token и подставляйте его в заголовок Authorization: Bearer <token> в запросах ниже.

Вариант 1. Настройка в iikoWeb (без API)

Этот способ не требует программирования: настройки задаются прямо в веб-интерфейсе iikoWeb.

В iikoWeb откройте раздел «Настройка Cloud API».
Выберите нужный API-ключ — тот, через который вы подключаетесь к iiko API.
Перейдите во вкладку «Подключенные точки» — это список организаций, к которым у ключа есть доступ.
Поставьте галочку напротив точки, по которой нужно получать вебхуки.
Нажмите «Настройка веб-хуков».
В появившейся панели справа заполните настройки:
- вкладка «Основное»:
  - URI — адрес вашего сервера, куда iiko будет присылать вебхуки (тот же webHooksUri, что и в Варианте 2). Адрес должен быть доступен из интернета — для локальной отладки используйте ngrok;
  - токен авторизации — произвольная строка (authToken), по которой ваш сервер будет проверять, что вебхук прислала именно iiko (подробнее в разделе «Проверка подлинности вебхука»);
- вкладка «Фильтры» — выберите события, по которым нужно получать вебхук. Если нужны только уведомления о заказах доставки, оставьте только DeliveryOrderUpdate (и при необходимости DeliveryOrderError).
Обязательно нажмите «Применить» — без этого настройки не сохранятся.

Оба варианта (интерфейс iikoWeb и метод update_settings) задают одни и те же настройки. Проверить, что сохранилось, можно методом POST /api/1/webhooks/settings (см. Вариант 2).

Вариант 2. Настройка через API (curl)

Те же настройки можно задать методом POST /api/1/webhooks/update_settings.

Поля запроса:

organizationId — идентификатор организации (ресторана);
webHooksUri — URL, куда iiko будет присылать уведомления (адрес вашего сервера);
authToken — токен, по которому ваш сервер убедится, что вебхук прислала именно iiko.

curl -X POST "https://api-ru.iiko.services/api/1/webhooks/update_settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "ID_ОРГАНИЗАЦИИ",
    "webHooksUri": "https://ваш-домен.ru/webhook",
    "authToken": "ВАШ_СЛУЧАЙНЫЙ_ТОКЕН"
  }'

Проверить сохранённые настройки можно методом POST /api/1/webhooks/settings:

curl -X POST "https://api-ru.iiko.services/api/1/webhooks/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "ID_ОРГАНИЗАЦИИ"
  }'

Проверка подлинности вебхука (authToken)

Чтобы ваш сервер не принимал поддельные запросы от посторонних, используется токен авторизации:

Сгенерируйте любую случайную строку (например, длинный набор символов).
Задайте её как authToken — в iikoWeb (Вариант 1) или через update_settings (Вариант 2).
iiko будет присылать этот токен в заголовке Authorization каждого вебхука.
На сервере проверяйте, что полученный заголовок Authorization совпадает с вашим authToken. Если не совпадает — игнорируйте запрос.

Приём события: разбор на примере заказа доставки

Когда заказ доставки создаётся или изменяется, iiko присылает POST-запрос на ваш webHooksUri. Тело запроса — массив событий; событие DeliveryOrderUpdate выглядит так:

[
  {
    "eventType": "DeliveryOrderUpdate",
    "eventTime": "2026-10-09 14:15:22.123",
    "organizationId": "a1b2c3d4-0000-0000-0000-000000000000",
    "correlationId": "8a24d2a9-0000-0000-0000-000000000000",
    "eventInfo": {
      "id": "9f8e7d6c-0000-0000-0000-000000000000",
      "externalNumber": "12345",
      "organizationId": "a1b2c3d4-0000-0000-0000-000000000000",
      "creationStatus": "Success",
      "order": {
        "number": 12345,
        "status": "New",
        "phone": "+7 900 000-00-00",
        "whenCreated": "2026-10-09 14:15:22",
        "sum": 1230.5,
        "items": []
      }
    }
  }
]

Ключевые поля:

eventType — тип события; для заказов доставки всегда DeliveryOrderUpdate;
eventInfo.creationStatus — статус создания заказа; детали (eventInfo.order) заполнены, когда он равен Success;
eventInfo.order.status — статус заказа; новый заказ имеет статус New;
eventInfo.order.number — номер заказа;
eventInfo.order.items — состав заказа.

Чтобы обрабатывать только новые заказы, ваш сервер должен:

проверить eventType — убедиться, что это DeliveryOrderUpdate;
взять eventInfo.order.status и проверить, что он равен New;
ответить HTTP-кодом 200 — иначе iiko посчитает доставку неуспешной и повторит отправку.

Вебхук приходит на каждое изменение заказа, поэтому статус одного и того же заказа можно отслеживать в последующих событиях по eventInfo.id или номеру.

Проверка и отладка

Поднимите локальный сервер (например, на порту 8080) и пробросьте его через ngrok:
```
ngrok http 8080
```
Укажите адрес ngrok в webHooksUri (Вариант 1 или 2).
Создайте тестовый заказ доставки в iiko — на ваш сервер должен прийти вебхук.
Если вебхук не приходит, проверяйте по порядку: доступен ли ваш адрес из интернета, сохранены ли настройки (webhooks/settings), дошёл ли запрос до сервера (смотрите логи) и верный ли eventInfo.order.status в теле события.

Частые ошибки

Ошибка	Что значит и что делать
`401 Unauthorized`	Токен доступа неверный или истёк. Получите новый по `POST /api/v2/access_token`.
Вебхук не приходит	Адрес `webHooksUri` недоступен из интернета или настройки не сохранились. Проверьте `webhooks/settings` и доступность адреса.
iiko повторяет отправку	Ваш сервер не отвечает кодом `200`. Возвращайте `200` сразу после приёма.
Вебхук заблокирован	Сервер долго не отвечал кодом `200`. См. статью «Ограничения веб-хуков».
Поддельный запрос	Заголовок `Authorization` не совпал с `authToken`. Проверьте проверку токена на сервере.

Что дальше

Справочник по API — все методы iikoCloud, включая раздел Webhooks.
Подключение Telegram-бота — практический пример: бот присылает уведомление о новом заказе доставки.
Ограничения веб-хуков — правила корректной работы и критерии блокировки.

Что такое вебхук и зачем он нужен​

Какие события можно получать​

Ограничения, которые нужно знать заранее​

Что нужно до начала​

Вариант 1. Настройка в iikoWeb (без API)​

Вариант 2. Настройка через API (curl)​

Проверка подлинности вебхука (authToken)​

Приём события: разбор на примере заказа доставки​

Проверка и отладка​

Частые ошибки​

Что дальше​