Налаштування Webhook в KeyCRM

Розповідаємо, як налаштувати відправку вебхуків з KeyCRM в сторонню систему.
Написано Вадим Крижевський
Оновлено 4 місяці тому

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

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

Зверніть увагу! В KeyCRM доступні тільки вихідні вебхуки, із системи можна тільки відправляти дані на потрібні URL.

 

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

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

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

Протестувати відправку вебхука та подивитися, які дані ви отримаєте, можна з допомогою сервісу webhook.site.

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

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

Дія «Відправити 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 адреси зі статичними параметрами
Зверніть увагу! Додавання змінних, які підставлять дані до URL з замовлення чи картки, не доступне. Інформація з основних полів буде відправлена у форматі JSON на вказаний URL.

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

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

Важливо! Якщо ви маєте потребу отримати додаткову інформацію, наприклад, дані з додаткових полів, деталізацію оплат, інформацію по доставці, або інші параметри, вам необхідно здійснювати додаткові запити через API з потрібними значеннями в параметрі include

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

Теги: POST, GET, вебхук, webhook, вэбхук, подія зміни статусу, вихідні дані, отримати json, зміни по API.
Чи була наша стаття корисною?