Настройка вебхуков

Вставьте в поле «URL вебхука» в блоке «Отправка событий» адрес, который выдал Альбато. Чтобы получить адрес, создайте в Альбато подключение «Вебхук» и скопируйте ссылку целиком.

Включить отправку без адреса нельзя: форма покажет ошибку «Укажите полный адрес вебхука с https:// или http://.»

У магазина один адрес для всех событий. Если нужно, чтобы заказы и остатки обрабатывали разные связки, отправляйте всё на один вебхук, а в каждой связке Альбато поставьте условие по полю event.

Секрет — строка-ключ, известная только магазину и вашей связке. Магазин подписывает им каждый запрос: вычисляет по алгоритму HMAC-SHA256 подпись тела запроса и передаёт её в заголовке X-Webhook-Signature. По подписи получатель может проверить, что запрос пришёл от магазина. Сам секрет в запросе не передаётся.

Заполнить поле «Секрет подписи» можно двумя способами:

• нажать «Создать секрет» — панель сгенерирует случайную строку из 64 символов и сразу покажет её;
• ввести свою строку длиной до 500 символов.

Кнопка «Показать» открывает введённое значение, «Скрыть» прячет его обратно.

После сохранения секрет больше не отображается, под полем появится подсказка «Секрет задан и не показывается повторно». Чтобы оставить прежний секрет, при следующем сохранении не заполняйте поле. Чтобы сменить, введите или создайте новый.

Отметьте в блоке «События» только те события, которые обрабатывают ваши связки. В блоке 23 флажка, разложенных по группам: «Заказы», «Клиенты и сообщения», «Товары и остатки», «Исполнители», «Записи на услуги». Лишние события впустую запускают связки, вытесняют нужные записи из журнала доставок и передают в Альбато лишние данные покупателей (подробнее — в статье «Персональные данные»). Какие поля приходят в каждом событии, описано в статье «События вебхуков».

Кнопка «Выбрать все» отмечает все события, «Снять выбор» снимает отметки. Счётчик «Выбрано» показывает, сколько событий отмечено.

Магазин проверяет выбор в момент действия. Если отметить событие сегодня, вчерашние заказы в Альбато не уйдут: событие не создаётся задним числом.

Включите переключатель «Отправлять события в Albato» и нажмите «Сохранить настройки» — магазин начнёт отправлять отмеченные события. Переключатель стоит первым в блоке «Отправка событий», но включать его имеет смысл после того, как заполнены адрес и события: без адреса настройки с включённой отправкой не сохранятся. Без сохранения положение переключателя не действует.

Если выключить переключатель и сохранить, отправка встанет на паузу:

• новые события в очередь не попадают, и после снятия паузы они не появятся;
• события, которые уже ждали отправки, остаются в очереди без расхода попыток и уйдут после включения.

Пауза пригодится, когда связку в Альбато перестраивают и ей пока нельзя получать данные.

В блоке «Проверка доставки» на вкладке «Вебхуки» нажмите «Отправить тестовое событие» — та же кнопка есть на вкладке «Обзор». Магазин сразу отправит запрос на сохранённый адрес и подождёт ответ до 10 секунд.

Кнопка работает только с сохранёнными настройками и включённой отправкой.

Результат показывается под кнопкой:

• «Тестовое событие принято» и код ответа, например HTTP 200;
• «Проверка не пройдена» — получатель вернул другой код или не ответил. Под заголовком будет код или текст ошибки.

В раскрывающемся блоке «Ответ получателя» видно начало ответа, первые 512 байт. По нему можно найти причину ошибки.

Тестовое событие содержит только служебные данные:

{
  "event": "integration.test",
  "deliveryId": "0b7d3c1e-5f2a-4c7e-9d41-2a8f6e3b9c10",
  "timestamp": "2026-09-16T12:00:00Z",
  "integration": {
    "storeId": 1,
    "message": "test delivery from shop backend"
  }
}

Оно отправляется напрямую, минуя очередь, и в журнал доставок не попадает.

⚠️ Важно: тестовое событие подходит для проверки адреса, но не для настройки полей. Если в связке стоит условие event = order.created, тест её не запустит. Чтобы получить в Альбато поля заказа, оформите настоящий тестовый заказ.

Откройте вкладку «Журнал доставок» — появится список «Последние доставки»: 20 последних событий магазина, новые сверху. Список не обновляется сам, для свежих данных нажмите «Обновить журнал».

В каждой строке указаны название события, дата и время, число неудачных попыток и статус:

• «Ожидает отправки» — событие в очереди или ждёт повторной попытки;
• «Доставлено» — событие отправлено;
• «Ошибка» — все три попытки закончились неудачей.

В блоке «Подробности» показаны идентификатор доставки (то же значение приходит в поле deliveryId), код события и текст последней ошибки. Например, http status 404 означает, что по адресу вебхука ничего нет.

Статус «Доставлено» значит только то, что Альбато принял запрос. Выполнились ли шаги связки, смотрите в истории связки в самом Альбато.

Когда отправка на паузе, над списком появляется подсказка «Отправка на паузе. Ожидающие доставки продолжатся после включения.»

Магазин отправляет событие не сразу, а через очередь: событие ждёт, пока его заберёт фоновый процесс.

1. Раз в 10 секунд процесс берёт из очереди до 20 событий и отправляет их по одному запросом POST.
2. На ответ отводится 10 секунд. Код ответа от 200 до 299 означает успех.
3. При другом коде или без ответа вторая попытка будет через 5 секунд, третья — через 30 секунд. К этим паузам добавляется ожидание следующей проверки очереди.
4. После третьей неудачи событие получает статус «Ошибка». Сам магазин его больше не отправляет, даже если исправить адрес.

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

💡 Порядок прихода событий при повторных попытках может нарушиться, а одно событие может прийти дважды. Если связка создаёт сделки или строки в таблице, перед созданием ищите запись с тем же deliveryId или номером заказа, чтобы не получить дубль.

Тест показывает «Проверка не пройдена» с кодом 404

Адрес скопирован не полностью или подключение «Вебхук» в Альбато удалено. Скопируйте адрес заново, вставьте в поле «URL вебхука» и сохраните настройки.

После заказа в журнале нет новой записи

Проверьте, что событие отмечено, отправка включена и настройки сохранены. Затем проверьте, как сделано изменение: импорт из файла и прямые изменения в базе данных событий не создают. Журнал обновляется только по кнопке «Обновить журнал».

Событие долго висит в статусе «Ожидает отправки»

Посмотрите, не выключена ли отправка и подключена ли услуга: в обоих случаях очередь ждёт. Если всё включено, а статус не меняется дольше минуты, откройте «Подробности» — там будет текст последней ошибки. Если ошибки нет, обратитесь в поддержку.

В журнале «Доставлено», а связка не сработала

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

Почему тестового события нет в журнале доставок?

Тест отправляется сразу, минуя очередь, и его результат показывается только под кнопкой «Отправить тестовое событие». В журнал попадают события, которые создают действия в магазине: заказы, оплаты, изменения остатков и другие отмеченные в настройках.

Можно ли отправить событие со статусом «Ошибка» ещё раз?

Нет, кнопки повторной отправки нет. Исправьте причину — обычно это адрес или выключенная связка в Альбато — и повторите действие в магазине. Если нужно получить данные уже случившегося заказа, запросите его через API по номеру — для этого связке нужен API-токен с правом чтения заказов.

Что будет с событиями, пока отправка на паузе?

Новые события на паузе не создаются и после включения не появятся. События, которые уже стояли в очереди до паузы, сохранятся и уйдут в Альбато после включения, попытки на них не тратятся.