Использование вебхуков позволяет сообщать внешним системам о различных событиях, которые произошли в KeyCRM и получать базовую информацию по заказам или карточкам воронок в которых именно они произошли.
Для отправки вебхуков используется триггерная автоматизация. Вы можете настроить срабатывание триггеров по различным условиям под различные потребности, например:
- в заказе зарезервированы или списаны товары;
- получена оплата по заказу;
- создана карточка в воронке или она перешла на определенный этап обработки.
Настройка действия по отправке Webhook
У нас есть подробные инструкции создания триггеров для заказов и воронок, поэтому сейчас рассмотрим только само действие отправки вебхука. Для этого:
- Выберите действие «Отправить Webhook» в настройках триггера;
- Откроется окно, в котором вам нужно ввести URL-адрес вебхука, куда будут отправляться данные, и выбрать метод передачи данных (POST или GET);
- Убедитесь, что вы правильно ввели URL-адрес и метод передачи данных;
- Сохраните настройки вебхука, чтобы изменения вступили в силу.
Процесс отправки вебхука
Если все заданные условия выполняются - срабатывает триггер и выполняет все настроенные действия в нем.
Действие «Отправить Webhook» автоматически отправляет запрос с данными в формате JSON на указанный URL-адрес с методом, который вы выбрали.
Независимо от выбранного метода всегда отправляются 2 стандартных параметра:
- «event» - событие по которому сработал триггер, который отправлялся по вебхуку. На данный момент доступны три события:
"order.change_order_status" // изменение статуса заказа "order.change_payment_status" // изменение статуса оплаты заказа "lead.change_lead_status" // изменение статуса карточки воронки - «context» - контекст, данные сущности по которой сработал вебхук.
Получив данные, ваш сервер должен отправить в ответ код 200, который означает, что запрос был успешно обработан. KeyCRM делает 3 попытки отправки данных, и если не получает успеха, прекращает отправку.
Если вам нужно отправить дополнительные данные вместе с запросом GET, вы можете добавить свои статические параметры в URL.
Они также будут переданы вместе с запросом, и вы сможете получить и обработать их во внешней системе.
https://webhook.site/a6d5120f-cdf1-4765-bfd3-5a699db72e22?test=test // пример url адреса со статическими параметрамиИнформация, которая отправляется через вебхук
Через вебхуки отправляется только базовая информация по заказам и карточкам воронок. Однако, она включает все основные параметры, такие как ID сущности, ID покупателя, сумма оплаты и т.д.
Важно! Если вы нуждаетесь получить дополнительную информацию, например, данные из дополнительных полей, детализацию оплат, информацию по доставке, или другие параметры, вам необходимо осуществлять дополнительные запросы через API с нужными значениями в параметре include:
- получить заказ по ID - GET /order/{orderId};
- получить карточку воронки по ID - GET /pipelines/cards/{cardId}.
Информация которая отправляется по каждому заказу в формате 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 // Сумма за товары в карточке
}
}
