Настройка Webhook в keyCRM

Рассказываем, как настроить отправку вебхуков из keyCRM в стороннюю систему.
Автор Вадим Крижевський
Обновлено 1 неделю назад

Отправка HTTP-запросов (исходящих вебхуков) позволяет автоматически уведомлять внешние системы о событиях в keyCRM и передавать необходимые данные.

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

  • создан заказ или изменен его статус;
  • в заказе зарезервированы или списаны товары;
  • получена оплата по заказу;
  • создана карточка в воронке или она перешла на определенный этап обработки. 
Обратите внимание! В keyCRM доступны только исходящие вебхуки, из системы можно только отправлять данные на нужные URL.

Как настроить действие «Отправить HTTP-запрос»

Процесс создания триггеров описан в отдельных инструкциях для заказов и воронок.

Ниже рассмотрим настройки самого действия «Отправить HTTP-запрос»:

  1. HTTP-метод запроса — выберите из списка: POST (по умолчанию), GET, PUT, PATCH или DELETE;
  2. Ссылка — введите URL-адрес внешнего сервиса. Поддерживаются только протоколы http:// и https://. Использование частных/локальных IP-адресов (например, localhost, 127.0.0.1, 192.168.x.x) запрещено;
  3. Указать собственные параметры (при необходимости) — включите переключатель для настройки заголовков и тела запроса:
  • Headers — если включить, будут передаваться Content-Type: application/json и собственные заголовки (до 20 в формате «Ключ — Значение»). Если отключено — отправляются стандартные заголовки.
  • Body (JSON) — если включить, вы сможете сформировать собственный JSON-объект только с теми полями, которые вам нужны. Если отключено — передается стандартный набор полей сущности.

    Доступные для использования переменные полей в раскрывающемся списке «Вставить поле». Для настройки структуры JSON поддерживается синтаксис Twig (условия, циклы, фильтры). Для проверки синтаксиса воспользуйтесь кнопкой «Проверить JSON».
Протестировать отправку вебхука и посмотреть, какие данные вы получите, можно с помощью сервиса webhook.site.

Процесс отправки и структура данных

Если все заданные условия выполняются — срабатывает триггер и выполняет настроенное действие «Отправить HTTP-запрос».

Система автоматически отправляет запрос в формате JSON на указанный URL-адрес с выбранным методом (POST, GET, PUT, PATCH, DELETE).

Вы можете добавить к URL собственные статические параметры:

https://webhook.site/a6d5120f-cdf1-4765-bfd3-5a699db72e22?test=test // пример url адреса со статическими параметрами

Обратите внимание! Добавление переменных, которые подставят данные в URL с заказа или карточки, недоступно. Информация с основных полей будет отправлена ​​в формате JSON на указанный URL.

1. Стандартная отправка данных (без пользовательских параметров).

Если переключатель «Указать пользовательские параметры» отключен, система отправляет стандартный набор данных.

Независимо от выбранного метода всегда отправляются 2 стандартных параметра:

  • «event» - событие по которому сработал триггер, который отправлялся по вебхуку. На данный момент доступны три события:
    "order.change_order_status" //  изменение статуса заказа
    "order.change_payment_status" // изменение статуса оплаты заказа
    "lead.change_lead_status" // изменение статуса карточки воронки
  • «context» - контекст, данные сущности по которой сработал вебхук.
Пример стандартного JSON для заказов.
{
  "event": "order.change_payment_status", // Событие, в данном случае изменение статуса оплаты заказа
  "context": {    
    "id": 67526, // Идентификатор заказа
    "source_uuid": null, // Уникальный идентификатор заказа из загруженного источника
    "global_source_uuid": null, // Глобальный уникальный идентификатор заказа из загруженного источника
    "status_on_source": null, // Идентификатор статуса на источнике
    "source_id": 246, // Идентификатор источника
    "client_id": 88282, // Идентификатор покупателя
    "grand_total": 45.22, // Общая стоимость заказа
    "total_discount": 1.8, // Общая сумма скидки
    "margin_sum": 40.22, // Сумма прибыли
    "expenses_sum": 1, // Сумма расходов
    "discount_amount": 1, // Скидка в целых значениях
    "discount_percent": 2, // Скидка в процентах
    "shipping_price": "2.00", // Стоимость доставки
    "taxes": "4.00", // Сумма налогов
    "register_id": null, // Системный идентификатор
    "fiscal_result": [], // Результаты фискализации
    "fiscal_status": "done", // Статус фискализации заказа
    "shipping_type_id": null, // Идентификатор типа доставки
    "manager_id": 108, // идентификатор ответственного менеджера
    "status_group_id": 5, // Идентификатор группы статуса заказа
    "status_id": 12, // Идентификатор статуса заказа
    "closed_from": null, // Закрыт из (источник)
    "status_changed_at": "2024-05-28T09:34:10.000000Z", // Время изменения статуса в UTC формате
    "status_expired_at": null, // Время просрочки статуса
    "parent_id": null, // Идентификатор родительского заказа, если это копия
    "manager_comment": null, // Комментарий менеджера
    "client_comment": null, // Комментарий клиента
    "discount_data": { // Данные о персональных скидках
      "loyalty": { // Информация о программе лояльности, которая применена в заказе
        "name": "Первый уровень", // Название уровня лояльности
        "amount": 100, // Сумма для достижения уровня
        "discount": 6, // Скидка на этом уровне
        "level_id": 22, // Идентификатор уровня лояльности
        "loyalty_program_id": 12 // Идентификатор программы лояльности
      },
      "individual": { // Индивидуальная скидка покупателя
        "discount": 25 // Размер индивидуальной скидки
      }
    },
    "is_gift": true, // Подарок или нет
    "promocode": "promo2024", // Промокод
    "wrap_price": "1.00", // Стоимость подарочной упаковки
    "gift_wrap": false, // Подарочная упаковка, наличие или отсутствие
    "payment_status": "part_paid", // Статус оплаты заказа
    "gift_message": null, // Поздравительное сообщение
    "last_synced_at": null, // Дата последней синхронизации с источником в UTC формате
    "created_at": "2024-05-28T09:24:01.000000Z", // Дата создания заказа в CRM в UTC формате
    "updated_at": "2024-05-28T09:34:20.000000Z", // Дата последнего изменения в заказе в UTC формате
    "closed_at": "2024-05-28 09:34:10", // Дата закрытия заказа в UTC формате - переход заказа в группу выполнен или отменен
    "deleted_at": null, // Дата удаления
    "ordered_at": "2024-05-28T09:24:01.000000Z", // Дата создания заказа на источнике в UTC формате
    "source_updated_at": null, // Дата последнего обновления из источника
    "payments_total": 40.02, // Общая сумма платежей
    "is_expired": false, // Просрочен заказ или нет
    "has_reserves": false // Есть ли резерв товара
  }
}
Пример стандартного JSON для карточек.
{
  "event": "lead.change_lead_status", // Событие, в данном случае изменение статуса карточки
  "context": {
    "id": 13898, //Идентификатор карточки воронки
    "title": "Чат с Your Dev", //Название карточки
    "contact_id": 14860, //Идентификатор контактного лица карточки воронки
    "manager_id": 108, // Идентификатор ответственного менеджера
    "target_id": null, // Идентификатор созданной на основе карточки сущности
    "target_type": null, // Тип созданной на основе карточки сущности. Возможные варианты: order (заказ), lead (карточка)
    "source_id": 245, // Идентификатор источника
    "status_id": 1009, // Идентификатор статуса карточки воронки
    "pipeline_id": 94, // Идентификатор воронки
    "status_changed_at": "2024-05-28T09:35:31.000000Z", // Дата изменения статуса карточки воронки в UTC формате
    "communicate_at": "2024-05-17T13:08:33.000000Z", // Дата и время планируемого контакта по карточке воронки в UTC формате
    "currency_code": "UAH", // Валюта товаров и оплат в карточке
    "manager_comment": "", // Комментарий менеджера
    "utm_source": null, // Источник кампании
   "utm_medium": null, // Тип трафика
    "utm_campaign": null, // Название кампании
    "utm_term": null, // Ключевое слово
    "utm_content": null, // Идентификатор объявления
    "is_finished": false, // Идентификатор закрытия карточки воронки
    "closed_from": null,
    "created_at": "2024-05-17T13:08:33.000000Z", // Дата создания карточки воронки в UTC формате
    "updated_at": "2024-05-28T09:35:31.000000Z", // Дата последнего изменения карточки воронки в UTC формате 
    "payments_total": 15000, // Сумма оплат в карточке
    "products_total": 15000 // Сумма за товары в карточке
  }
}

Отправка данных с собственным JSON-объектом

Если вы включили переключатель «Указать собственные параметры» и настроили Body (JSON), вы можете самостоятельно определять структуру и передавать только нужные вам поля с помощью переменных и шаблонизатора Twig.

Обратите внимание! Некоторые переменные для заказов и воронки продаж различаются, поэтому примеры для заказов не будут работать для воронки продаж и наоборот!

Примеры настраиваемого JSON для заказов:

Дополнительное поле из карточки покупателя и номер ТТН.
{
  «№ заказа»: «{{ model.id }}»,
  «Клиент (ЕГРПОУ)»: «{{ model.CT_1886 }}»,
  «ТТН»: «{{ model.tracking_code }}»
}
Список товаров: название, цена, количество.

Обратите внимание! Поскольку товары в заказе хранятся в массиве, для формирования JSON с данными каждого товара необходимо использовать цикл Twig {% for %}.

{
  «№ заказа»: «{{ model.id }}»,
  «Товары»: [
    {% for product in model.products %}
    {
      «Название»: «{{ product.product_name }}»,
      «Цена»: {{ product.product_price | default(0) }},
      «Количество»: {{ product.product_quantity | default(1) }}
    }{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}
Данные об оплатах со ссылкой на фискальный чек.

Обратите внимание! Поскольку оплаты заказа хранятся в массиве, для формирования JSON с данными каждой оплаты необходимо использовать цикл Twig {% for %}.

{
  «order_id»: {{ model.id }},
  «grand_total»: {{ model.grand_total|default(0) }},
  «payment_status»: «{{ model.payment_status }}»,
  «paid_total»: {{ model.payments_total|default(0) }},
  «remaining_to_pay»: {{ (model.grand_total - model.payments_total)|round(2) }},
  «fully_paid»: {{ (model.grand_total - model.payments_total) <= 0 ? „true“ : „false“ }},
  «payments»: [
  {% for payment in model.payments %}
  {
    «amount»: {{ payment.amount|default(0) }},
    «status»: «{{ payment.status }}»,
    «description»: «{{ payment.description|default(„“)|replace({„»“: „“, «\n»: „ “}) }}",
    «payment_date»: {% if payment.status == „paid“ and payment.payment_date %}«{{ payment.payment_date|date(„d.m.Y H:i“) }}»{% else %}null{% endif %},
    «fiscal_url»: «{{ payment.fiscal_url|default(„“) }}»
  }{% if not loop.last %},{% endif %}
  {% endfor %}
]
}

Примеры настраиваемого JSON для воронки продаж:

Статус карты, менеджер, имя клиента и время создания.
{
  «Воронка»: «{{ model.pipeline }}»,
  «id карты»: {{ model.id }},
  «Статус карты»: «{{ model.status }}»,
  «Менеджер»: «{{ model.manager }}»,
  «Имя клиента»: «{{ model.contact_name }}»,
  «Время создания»: «{{ model.created_at|date(„d.m.Y H:i“) }}»
}
Название карточки и UTM-метки.
{
  «card_id»: {{ model.id }},
  «title»: «{{ model.title|default(„“)|replace({„»“: „“}) }}",
  «utm»: {
    «source»: «{{ model.utm_source|default(„“) }}»,
    «medium»: «{{ model.utm_medium|default(„“) }}»,
    «campaign»: «{{ model.utm_campaign|default(„“) }}»,
    «term»: «{{ model.utm_term|default(„“) }}»,
    «content»: «{{ model.utm_content|default(„“) }}»
  },
  «created_at»: «{{ model.created_at|date(„d.m.Y H:i“) }}»
}
Список товаров: название, цена, количество.

Обратите внимание! Поскольку товары в карточке хранятся в массиве, для формирования JSON с данными каждого товара необходимо использовать цикл Twig {% for %}.

{
  «card_id»: {{ model.id }},
  «products_total»: {{ model.products_sum|default(0) }},
  «products»: [
    {% for product in model.products %}
    {
      «name»: «{{ product.name|default(„“)|replace({„»“: „“}) }}",
      «price»: {{ product.price|default(0) }},
      «quantity»: {{ product.quantity|default(1) }}
    }{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}
Данные об оплатах с расчетом остатка к оплате.

Обратите внимание! Поскольку данные об оплатах по карте хранятся в массиве, для формирования JSON с данными каждой оплаты необходимо использовать цикл Twig {% for %}.

{% set paid = 0 %}
{% for payment in model.payments %}
  {% if payment.status == «paid» %}
    {% set paid = paid + payment.amount %}
  {% endif %}
{% endfor %}
{
  «card_id»: {{ model.id }},
  «payment_status»: «{{ model.payment_status|default(„“) }}»,
  «products_total»: {{ model.products_sum|default(0) }},
  «paid_total»: {{ paid|round(2) }},
  «remaining_to_pay»: {{ (model.products_sum - paid)|round(2) }},
  «fully_paid»: {{ (model.products_sum - paid) <= 0 ? „true“ : „false“ }},
  «payments»: [
    {% for payment in model.payments %}
    {
      «type»: «{{ payment.type|default(„“) }}»,
      «amount»: {{ payment.amount|default(0) }},
      «status»: «{{ payment.status|default(„“) }}»,
      «description»: «{{ payment.description|default(„“)|replace({„»“: „“, «\n»: „ “}) }}",
      «payment_date»: {% if payment.status == „paid“ and payment.payment_date %}«{{ payment.payment_date|date(„d.m.Y H:i“) }}»{% else %}null{% endif %}
    }{% if not loop.last %},{% endif %}
    {% endfor %}
  ]
}

Обработка ответов, повторные попытки и уведомления

  • Таймаут: лимит ожидания ответа от сервера-получателя составляет 10 секунд;
  • Успешное выполнение: сервер-получатель должен вернуть статус-код группы 2xx (например, 200 OK);
  • Ошибки запроса и отклонения (коды 3xx и 4xx): если сервер-получатель возвращает такие коды (например, 404 Not Found, если указан несуществующий адрес, или 401 Unauthorized), система немедленно прекращает выполнение действия без повторных попыток;
  • Ошибки сервера (коды 5xx) и таймауты: система автоматически осуществляет 3 повторные попытки отправки с паузами в 1, 5 и 15 минут. 
    Во время повторных попыток отправляется снимок данных, зафиксированный в момент первой отправки;
  • Логирование и уведомления: запуск выполнения действия фиксируется в истории изменений заказа или карточки воронки. Если запрос завершился ошибкой 3xx, 4xx или если все 3 повтора для 5xx/таймаута оказались неудачными, ответственный менеджер и администраторы получают системное уведомление:

Теги: HTTP-запрос, HTTP-запрос, веб-хук, webhook, веб-хук, вэбхук, POST, GET, PUT, PATCH, DELETE, Headers, заголовки, Body, тело запроса, JSON, событие изменения статуса, событие создания лида.
Оцените эту статью