Відправка 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 у тілі запиту.
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 // Сума за товари у картці
}
}
2. Відправка даних із власним 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/таймауту виявилися невдалими, відповідальний менеджер та адміністратори отримують системне сповіщення:
