Webhook — интеграция с любыми внешними системами через веб-хуки

REST API является наиболее популярным способом интеграции независимых онлайн-систем друг с другом. Ainox поддерживает интеграцию с внешними системами через веб-хуки. Это значит, что на любые события, мы можем отправлять во внешнюю систему сигнал, содержащий полный набор необходимых данных.

Зачем нужны веб-хуки

Функционал Ainox подразумевает только обработку заявок, счетов и учет подписчиков. Но для полноценной работы этого может быть недостаточно. Возможно у вас есть своя CRM-система, вы хотите сохранять данные во внешнюю базу данных, получать уведомления или интегрировать нас с любым другим сервисом, чтобы мгновенно узнавать о статусе заявок, счетов и подписчиков в Ainox. Веб-хуки лучший способ решить эту задачу.

Где искать инструкцию по интеграции с внешними системами

Чаще всего вы можете найти инструкцию по интеграции в разделе работы с API в файле справки. Там указан способ получения URL для отправки веб-хука и способы настройки.

Триггеры для веб-хуков

• Получена новая заявка;
• Заявка оплачена;
• Подписчик активирован;
• Нет оплаты по подписке;
• Подписчик деактивирован;
• Подписчик отписался.

Описание событий:

Получена новая заявка - событие о созданной заявке, заявка может быть не оплачена.

Заявка оплачена - событие об оплаченной заявке, выполняется на каждую оплату по заявке.

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

Нет оплаты по подписке - событие о неоплаченной заявке по активной подписке.

Подписчик деактивирован - событие на деактивацию подписчика в системе. Деактивировать подписчика может только администратор системы.

Подписчик отписался - событие на отписку подписчиком, подписчик отписался самостоятельно.

На любое из этих событий вы можете настроить исходящий веб-хук во внешнюю систему, чтобы передать данные заказа или подписчика.

Важно! Если сервер оказался недоступен при попытке отправить данные в момент события, мы совершаем еще 4 попытки с интервалом: 5 минут, 15 минут, 1 час и 24 часа.

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

Веб-хуки доступны каждому пользователю при редактировании существующего коннектора. Для этого вам нужно перейти в уже созданный коннектор и найти блок «Веб-хуки».

Перейдите в раздел Коннекторы и нажмите кнопку «Редактировать» возле нужного.

Возможности веб-хуков

1. Отправка HTTP уведомлений методом «GET», «POST» и «INPUT» — это «POST» с данными в JSON формате;
2. Отправка на любой URL указанный пользователем, с ожиданием положительного ответа до 24 часов;
3. Возможность задавать собственные конфигурации уведомлений, с использованием динамических переменных, созданием собственных значений и массивов с вложенностью до 2-х уровней, задавать собственные названия полей ввода;

Как создать веб-хук

1. В разделе «Веб-хуки» нажмите кнопку «Добавить веб-хук»;
2. В открывшемся окне укажите название веб-хука. Оно нужно только для вас, чтобы вы смогли различать их в списке;
3. Выберите тип события, триггер, на который будет срабатывать веб-хук;
4. Выберите метод отправки данных, чаще всего это INPUT;
5. Укажите Адрес, URL внешней системы;
6. Соберите дополнительные параметры веб-хука;
7. Сохраните веб-хук. Веб-хук сохраняется автоматически, не зависимо от изменений в коннекторе.

Важно! Значения переменных фиксируются при создании подписчика и если изменить значение переменных в вебхуках, по которым уже были созданы события с активными подписками, то данные по ранее созданным подпискам не будут заполняться по измененным переменным.

Настройка дополнительных параметров

Мы создали специальный конфигуратор, который позволяет вам собрать и отправить любой набор данных, в зависимости от требований внешней системы. В качестве образца мы по умолчанию размещаем там важные, дополнительные данные, которые будут отправлены с веб-хуком.

Что важно знать:

• Вы можете задавать сколько угодно собственных переменных в формате var = value;
• В качестве значений вы можете использовать значения системных переменных, они помещаются в фигурные скобки, например {id};
• Вы можете создавать вложенный массив с данными, используя квадратные скобки, например [data];
• Каждая строка разделяется символом точки с запятой «;», важно их использовать, иначе будут ошибки в обработке значений.

Пример

my_variable = мое собственное значение;

[data];

ID={id};

Subscriber={id_subscriber};

Date={date};

Важно! Обращайте внимание на отсутствие пробелов возле переменных и значений. Добавленные пробелы могут передаваться в веб-хуке и вызывать ошибки во внешних системах.

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

{connector} - имя коннектора

{id_subscriber} -  id подписчика

{price} - цена 

{date} - дата платежа

{id} - id товара

{itemname} - наименование товара

Как задать названия полей ввода

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