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

Розповідаємо як налаштувати відправку вебхуків з KeyCRM в сторонню систему.
Написано Богдан Починок
Оновлено 9 місяців тому

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

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

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

Детально як працюють тригери та як їх правильно налаштувати описано в інструкції: Автоматизація в KeyCRM. У даній статті ми розглянемо саме дію відправки вебхуків.

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

 

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

Щоб налаштувати відправку вебхуку, вам потрібно виконати наступні кроки:

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

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

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

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

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

  • «event» - подія по якій спрацював тригер, котрий відправлявся по вебхуку;
  • «context»- контекст, дані сутності по якій спрацював вебхук; 

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

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

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

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

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

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

Для цього скористайтеся запитом GET/order/{orderId} з потрібними значеннями в параметрі include.

Інформація яка відправляється по кожному замовленню в форматі json:

{
  "event": "order.change_order_status",  // Подія, в цьому випадку зміна статусу замовлення
  "context": {
    "id": 56076,  // Ідентифікатор замовлення
    "source_uuid": null,  // Унікальний ідентифікатор замовлення із завантаженого джерела
    "status_on_source": null,  // Ідентифікатор статусу на джерелі
    "source_id": 140,  // Ідентифікатор джерела
    "client_id": 17296,  // Ідентифікатор id покупця
    "grand_total": 22000,  // Фінальна вартість
    "total_discount": 0,  // Сума знижки
    "expenses_sum": 0,  // Сума витрат
    "discount_amount": 0,  // Знишка в цілих значеннях
    "discount_percent": 0,  // Знишка у відсотках
    "shipping_price": null,  // Вартість доставки
    "taxes": null,  // Сума податків
    "fiscal_result": [],  // Результати фіскалізації
    "fiscal_status": null,  // Статус фіскалізації
    "manager_id": 62,  // ID менеджера
    "status_group_id": 4,  // Ідентифікатор групи статусу замовлення
    "status_id": 28,  // Ідентифікатор статусу замовлення
    "status_changed_at": "2023-03-20T09:53:49.000000Z",  // Час зміни статусу в UTC форматі
    "parent_id": null,  // Ідентифікатор батьківського замовлення
    "manager_comment": null,  // Коментар менеджера
    "client_comment": null,  // Коментар клієнта
    "is_gift": false,  // Подарунок чи ні
    "promocode": null,  // Промо код
    "wrap_price": null,  // Вартість подарункової упаковки
    "gift_wrap": false,  // Подарункова упаковка, наявність або відсутність
    "payment_status": "not_paid",  // Статус оплати
    "gift_message": null,  // Вітальне повідомлення
    "last_synced_at": null,  // Дата останньої синхронізації із джерелом в UTC форматі
    "created_at": "2023-03-17T18:36:34.000000Z",  // Дата створення замовлення в UTC форматі
    "updated_at": "2023-03-20T09:53:49.000000Z",  // Дата останньої зміни замовлення в UTC форматі
    "closed_at": null,  // Дата закриття замовлення в UTC форматі
    "deleted_at": null,  // Дата видалення
    "ordered_at": "2023-03-17T18:36:34.000000Z",  // Дата замовлення на джерелі в UTC форматі
    "payments_total": 0,  // Загальна сума платежів
    "is_expired": false,  // Протерміноване замовлення чи ні
    "has_reserves": false  // Чи є резерв товару 
  }
}

Інформація яка відправляється по карткам у воронках в форматі json:

{
  "event": "lead.change_lead_status",
  "context": {
    "id": 8043, 
    "title": "№110002", 
    "contact_id": 8559, 
    "manager_id": 108, 
    "target_id": null,
    "target_type": null,
    "source_id": 141,
    "status_id": 678,
    "pipeline_id": 63,
    "status_changed_at": "2023-08-07T08:37:58.000000Z",
    "communicate_at": "2023-08-18T10:42:06.000000Z",
    "currency_code": "UAH",
    "manager_comment": "Коментар",
    "utm_source": "facebook",
    "utm_medium": "banner",
    "utm_campaign": "sale",
    "utm_term": "landing page",
    "utm_content": "-30%",
    "is_finished": false,
    "closed_from": null,
    "created_at": "2023-06-07T09:42:06.000000Z",
    "updated_at": "2023-08-07T08:37:58.000000Z",
    "deleted_at": null,
    "source_uuid": null,
    "payments_total": 0,
    "products_total": 124.5
  }
}

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