Використання вебхуків дозволяє повідомляти зовнішні системи про різні події, які відбулися у KeyCRM та отримувати базову інформацію по замовленням чи карткам воронок в яких саме вони відбулись. 

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

• в замовленні зарезервовано чи списано товари;
• отримана оплата по замовленню;
• створена картка у воронці або вона перейшла на певний етап обробки. 

Налаштування дії по відправці Webhook

Ми маємо детальні інструкції створення тригерів для замовлень та воронок, тому зараз розглянемо тільки саму дію відправки вебхука. Для цього:

1. Виберіть дію «Відправити Webhook» у налаштуваннях тригера;
2. Відкриється вікно, в якому вам потрібно ввести URL-адресу вебхука, куди будуть відправлятися дані, та вибрати метод передачі даних (POST або GET);
3. Переконайтеся, що ви правильно ввели URL-адресу та метод передачі даних;
4. Збережіть налаштування вебхука, щоб зміни набули чинності.

Процес відправки вебхука

Якщо всі задані умови виконуються — спрацьовує тригер і виконує всі налаштовані дії у ньому.

Дія «Відправити Webhook» автоматично відправляє запит з даними у форматі JSON на вказану URL-адресу з методом, який ви обрали.

Незалежно від обраного методу завжди відправляються 2 стандартні параметри:

1. «event» - подія по якій спрацював тригер, котрий відправлявся по вебхуку; На цей час доступні три події:
   

   "order.change_order_status" //  зміна статусу замовлення
   "order.change_payment_status" // зміна статусу оплати замовлення 
   "lead.change_lead_status" // зміна статусу картки воронки

2. «context» - контекст, дані сутності по якій спрацював вебхук.

Отримавши дані, ваш сервер має відправити у відповідь код 200, який означає, що запит був успішно оброблений. KeyCRM робить 3 спроби відправки даних, і якщо не отримує успіху, припиняє відправку.

Якщо вам потрібно відправити додаткові дані разом із запитом GET, ви можете додати свої статичні параметри до URL.

Вони також будуть передані разом із запитом, і ви зможете отримати та обробити їх у зовнішній системі.

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

Інформація яка відправляється через вебхук

Через вебхуки відправляється тільки базова інформація по замовленням та карткам воронок. Однак, вона включає всі основні параметри, такі як ID сутності, ID покупця, сума оплати і т.д.

Інформація яка відправляється по кожному замовленню в форматі 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   // Сума за товари у картці
  }
}