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

Адрес выдаёт Альбато. Создайте там подключение «Вебхук», скопируйте ссылку целиком и вставьте её в поле «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 секунд. Код  2хх означает успех.
3. При другом коде или без ответа вторая попытка будет через 5 секунд, третья — через 30 секунд. К этим паузам добавляется ожидание следующей проверки очереди.
4. После третьей неудачи событие получает статус «Ошибка». Автоматически оно больше не отправляется, даже если исправить адрес.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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