Настройки магазина

Как настроить вебхуки для отправки событий заказов и сессий в API или на email?

Создавайте и управляйте вебхуками магазина в Настройках: выберите API или E-mail, событие session-created, order-created или order-updated, используйте URL с {{placeholder}}, узнайте о лимите в 20 вебхуков, повторных попытках и письме владельцу после 5 сбоев подряд.

Что делают вебхуки

Вебхук подписывается на конкретное событие магазина. Когда это событие происходит, Storeep немедленно отправляет данные события на указанный вами URL (тип API) или на указанный вами email-адрес (тип E-mail). Вебхуки часто используются для интеграций отслеживания заказов, синхронизации с CRM, конверсий рекламных платформ и автоматических уведомлений.

Чтобы управлять вебхуками, перейдите в Настройки → Вебхуки. Для просмотра или изменения вебхуков нужно разрешение settings.

Лимиты вебхуков

Максимум 20 вебхуков на магазин. Попытка добавить 21-й возвращает ошибку "You have reached the maximum of 20 webhooks per store".
В списке вебхуки показаны сначала новые, с разбивкой по 40 на страницу.

Создание вебхука

Нажмите Add new webhook, заполните поля ниже, затем нажмите Add.

Activate

Отмечено по умолчанию. Когда отмечено, вебхук активен в момент сохранения, и подходящие события отправляются. Снимите отметку, чтобы сохранить вебхук в отключенном состоянии, в котором он ничего не получает. Это можно переключить в любой момент, отредактировав вебхук.

Name

Обязательно. Максимум 50 символов.
Понятная метка, отображаемая в списке, например Facebook CAPI order created.

Type

API: Storeep отправляет HTTP-запрос POST с данными события на ваш URL.
E-mail: Storeep отправляет письмо с данными события на ваш адрес.

Event

Событие магазина, которое запускает вебхук. Существует три события:

Session created: в вашем магазине создается новая сессия посетителя.
Order created: размещен новый заказ.
Order updated: статус или данные существующего заказа изменились.

Важно: тип E-mail доставляет только Order created и Order updated. Если выбрать E-mail с Session created, вебхук сохранится, но ничего не будет отправлять. Используйте тип API, если вам нужно событие сессии.

Format

Только один вариант, Json: данные отправляются как документ JSON.

URL (только для типа API)

Обязательно, когда тип API. Максимум 500 символов.
Поле уже показывает префикс https://, поэтому вводите только хост и путь, например api.example.com/events/order. Если вы вставите полный адрес с https:// или http://, префикс будет удален перед сохранением.
Динамические плейсхолдеры: вставляйте любое поле из данных события в URL с помощью синтаксиса двойных фигурных скобок {{field_name}}. Пример: example.com/postback?cid={{fbclid}}&payout={{order_total}}. Значения кодируются для URL, а плейсхолдер с отсутствующим полем превращается в пустое значение. Это позволяет отправлять данные о конверсиях прямо на рекламную платформу без прокси.
Адрес проверяется после удаления плейсхолдеров, поэтому неверный URL возвращает "The url you have entered is incorrect".

Email-адрес (только для типа E-mail)

Обязательно, когда тип E-mail. Должен быть корректным адресом, максимум 127 символов.

Редактирование вебхука

Нажмите на любую строку, чтобы открыть редактор. Каждое поле можно изменить. Поле URL заполняется заранее, только если сохраненный тип, API, а поле email заполняется заранее, только если сохраненный тип, E-mail. Нажмите Save, чтобы применить. Сохранение со снятой отметкой Activate отключает вебхук без его удаления.

Столбцы списка вебхуков

Name: метка с датой создания.
URL / E-mail: назначение.
Type: API или E-mail.
Event: Session created, Order created или Order updated.
Format: Json.
Status: Activated или Deactivated.

Удаление вебхука

Выберите одну или несколько строк и нажмите Delete webhooks. Удаление безвозвратно и останавливает все будущие доставки для этой подписки.

Доставка, повторные попытки и письма о сбоях

Этот раздел относится к вебхукам типа API. Вебхуки типа E-mail отправляются по принципу "отправил и забыл": они посылаются один раз без повторных попыток и без отслеживания сбоев.

Поведение повторных попыток

У каждого запроса таймаут 5 секунд. Если цель возвращает ошибку 5xx, 429 (превышен лимит запросов) или недоступна (ошибка соединения), доставка считается временным сбоем и повторяется.
После первого неудачного запроса Storeep повторяет с экспоненциальной задержкой до 5 раз: примерно через 30 с, 60 с, 120 с, 240 с, затем 480 с. После последней попытки событие отбрасывается.
Ответ 4xx, кроме 429 (например, 404 или 403), считается постоянным сбоем. Storeep не повторяет его, потому что неверная или отклоняющая конечная точка сама себя не исправит.
Если у вас несколько вебхуков на одно событие, повторная попытка пересылает только тем, у кого произошел сбой. Конечные точки, уже вернувшие успех, пропускаются, поэтому вы не получите дублирующих доставок.

Письмо-уведомление о сбое

Storeep считает подряд идущие неудачные доставки по каждому вебхуку. После 5 сбоев подряд владелец магазина получает одно письмо с темой "Action needed: your Storeep webhook is failing", на языке владельца, с указанием имени вебхука, назначения, события и последнего кода статуса HTTP.
Вы получаете ровно одно письмо за серию сбоев. Дальнейшие письма не отправляются, пока этот вебхук не восстановится.
Как только доставка снова проходит успешно, счетчик сбоев обнуляется и уведомление перевзводится, поэтому будущая серия сбоев снова сможет вам написать.

Советы и подводные камни

Можно создать несколько вебхуков на одно событие, например отправлять Order created и в CRM, и на рекламную платформу как две отдельные записи.
Если вашей конечной точке нужна аутентификация, поместите токен в строку запроса URL, жестко прописав его или через {{placeholder}} из данных события, либо поставьте перед ней прокси, который добавит авторизацию перед пересылкой.
Session created срабатывает для каждой уникальной сессии посетителя и может быть очень частым на загруженных магазинах. Подписывайтесь на него, только если ваша конечная точка справится с нагрузкой, и помните, что оно работает только с типом API.