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

Процесс отправки и структура данных
Если все заданные условия выполняются — срабатывает триггер и выполняет настроенное действие «Отправить 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/таймаута оказались неудачными, ответственный менеджер и администраторы получают системное уведомление:
