Вебхук – це спеціальний код, за допомогою якого можна відслідкувати зміни на одному ресурсі та передати їх на інший ресурс у реальному часі.
Вебхуки в Uspacy – це спосіб автоматизувати роботу у Просторі. А саме автоматично «сигналізувати» про певні події, які відбуваються в Uspacy, стороннім сервісам. Або навпаки, дозволяють зовнішнім системам відправляти через спеціальну URL-адресу дані в Простір, де потім на їх основі виконати певну дію.
Саме тому в Uspacy можна працювати як з вихідними вебхуками, так і з вхідними.
Уся робота відбувається на однойменній сторінці Простору. Щоб перейти на неї потрібно розгорнути розділ Автоматизація.
🌟Зверніть увагу, що доступ до цього розділу мають тільки власник і адміністратор Простору.
⚙️ Оскільки ці дії передбачають певних технічних навичок і вмінь, то радимо роботи з налаштування вебхуків проводити саме спеціалістам-розробникам. Або ж ви завжди можете звернутися за допомогою до наших партнерів.
Вихідні
Як створити новий вихідний вебхук?
Щоб зробити це, натисніть на відповідну кнопку.
Відкриється вікно, де потрібно бути заповнити всі поля. Вибрати що саме та з яким об’єктом буде відбуватися, щоб на основі цих змін надіслати дані за межі Uspacy стороннім сервісам.
Подія – що саме повинно статися. Тобто, вебхук відпрацює, коли буде створено, змінено, видалено об’єкт чи змінено етап для нього.
Об’єкт події – те, з чим відбувається взаємодія. Тобто вебхук відпрацює, коли певну сутність, а саме лід, угоду, контакт, компанію, справу, завдання, допис чи коментар буде створено, змінено, видалено чи змінено етап для них.
❗️Зверніть увагу, що деякі сутності є несумісними з деякими подіями. Наприклад, не можна створити вебхук, який буде надсилати дані про зміну етапу для контакту, компанії, справи тощо. Оскільки це неможливо, спираючись на функціонал цих сутностей.
Активність – забезпечує роботу вебхука, після його підтвердження.
Кінцева точка за межами Uspacy – URL-адреса, на яку потрібно надсилати дані. Там розробник розміщує спеціальний код, який буде обробляти вхідні запити (повідомлення).
💡Ця адреса повинна бути дійсною та загальнодоступною. У полі її потрібно обов'язково прописувати з https://. Тобто https://MN.XY, де https:// – протокол, MN.XY – доменне ім'я.
Коли всі поля заповнені, натисніть Створити.
Вебхук одразу буде додано до загального переліку. Спочатку він отримає статус Непідтверджений. Тому, щоб вебхук почав коректно працювати потрібно його підтвердити. ⬇️
Як підтвердити вихідний вебхук?
Після створення вебхуку Uspacy надішле POST-запит на вашу URL-адресу кінцевої точки з підтверджувальним посиланням.
А ваш сервер повинен прийняти цей запит, видобути це посилання та перейти по ньому.
Готово ✅
Після цього вебхук отримає статус Підтверджений і буде працювати.
Корисні посилання та поради
Для підтвердження та обробки вхідних повідомлень можна використовувати готові хендлери Amazon SNS для різних мов та фреймворків.
🔍 PHP/Laravel: https://github.com/nipwaayoni/laravel-aws-sns
🔍 Python/Django https://gist.github.com/gaqzi/d3cf5e73afb42e535376
Приклад повідомлення про подію
{
"topic": "Notifications",
"type": "comment",
"env": "prod",
"data": {
"entity": {
"author_id": 1,
"entity_type": "task",
"entity_id": 786,
"message": "<p class=\"PlaygroundEditorTheme__paragraph\" dir=\"ltr\"><span>test<\/span><\/p>",
"date": 1690963631,
"id": 9087,
"mentioned": {
"users": [],
"departments": [],
"groups": []
},
"notify": {
"users": [
1
],
"groups": [],
"departments": []
}
},
"user_id": 1,
"service": "comments",
"domain": "my.uspacy.ua",
"timestamp": "2023-08-02T08:07:11.256570Z",
"action": "create"
},
"metadata": []
}
Вхідні
Як створити новий вхідний вебхук?
Щоб зробити це, натисніть на відповідну кнопку.
Відкриється вікно, де потрібно бути заповнити всі поля. А саме:
Назва – допомагає ідентифікувати новостворений вебхук серед інших. Може бути довільною і відображати короткий опис того, до буде відбуватися.
Доступи – той інструмент чи інструменти Простору, до яких вебхук матиме доступ. Відповідно Uspacy в межах цих сервісів (CRM, Завдання, Чати, справи тощо) приймає дані та виконує з ними певну дію відповідно до заданої логіки.
Активність – забезпечує роботу вебхука, одразу після його створення.
Коли всі поля заповнені, натисніть Створити.
Вебхук одразу буде додано до загального переліку. І він отримає статус Активований та буде готовий для використання.
Як використовувати вхідні вебхуки?
Після створення вхідного вебхука та надання йому доступів до потрібних інструментів, з’являється можливість використання Uspacy REST API свого Простору без необхідності авторизації за токеном.
Крім того, як ми вже знаємо, після створення вхідного вебхуку, система автоматично згенерує для нього унікальну адресу.
Її й потрібно використовувати для формування API-запиту.
🟣 Наприклад, якщо доступ був наданий до інструменту Завдання.
То конкретне завдання можна отримати за адресою:
{webhook_url}/tasks/v1/tasks/{task_id}
Тобто:
{webhook_url} – скопійована з вікна налаштування адреса вебхука;
/tasks/v1/tasks/{task_id} – відносний шлях до кінцевої точки відповідного сервісу (інструменту), до якого має доступ вебхук, знайти можна в документації по API.
🔍Опис відповідного методу в API документації.
Приклад API-запиту:
GET
Відповідь:
{
"id": "816",
"parentId": 250,
"title": "Task",
"setterId": "1",
"createdBy": "1",
"createdDate": 1732623300,
"departmentId": "1",
"groupId": "2",
"closedBy": "",
"responsibleId": "2",
"deadline": 0,
"closedDate": null,
"body": "<p class=\"PlaygroundEditorTheme__paragraph\" dir=\"ltr\"><span style=\"white-space: pre-wrap;\">опис</span></p><p class=\"PlaygroundEditorTheme__paragraph\" dir=\"ltr\"><span style=\"white-space: pre-wrap;\">Description</span></p>",
"status": "notScheduled",
"priority": "veryHigh",
"resultCommentId": "",
"requiredResult": false,
"acceptResult": true,
"timeTracking": true,
"timeEstimate": 0,
"template": false,
"templateId": 294,
"delegation": true,
"basicTask": false,
"taskType": "task",
"accomplicesIds": [
"2",
"3",
"4",
"36",
"37",
"43",
"44",
"45",
"46",
"47"
],
"auditorsIds": [
"2",
"3",
"4",
"36",
"37",
"43",
"44",
"45",
"46",
"47"
],
"kanbanStageId": "",
"elapsedTimes": {
"totalSeconds": 0,
"myTime": 0,
"elapsedTimes": []
},
"crmEntities": {
"deals": [
{
"id": 124,
"title": "Deal"
}
],
"companies": [
{
"id": 39,
"title": "Company"
}
],
"universal_entity": [
{
"id": 2,
"title": "Universal"
}
]
},
"scheduler": {
"taskId": 294,
"active": true,
"nextRun": 1732709700,
"dateStart": "09.10.2024",
"hourStart": 54900,
"dateStop": null,
"timezoneOffset": 3,
"deadlineDay": null,
"deadlineHour": null,
"currentIteration": null,
"iteration": null,
"period": "day",
"every": 1,
"dayOfWeek": null,
"dayOfMonth": null,
"weekOfMonth": null,
"stoppedByForce": 0,
"createdAt": 1728475564,
"updatedAt": 1728475564
}
}
🟣 Якщо ж у налаштуваннях для вхідного вебхука вибраний доступ до CRM.
То ви отримаєте можливість взаємодії з усіма CRM сутностями Простору через API.
Наприклад, запит на створення ліда буде виглядати наступним чином:
{webhook_url}/crm/v1/entities/{entity}
Тобто:
{webhook_url} – скопійована з вікна налаштування адреса вебхука;
/crm/v1/entities/{entity} – відносний шлях до кінцевої точки відповідного сервісу (інструменту), до якого має доступ вебхук, знайти можна в документації по API.
🔍Опис відповідного методу в API документації.
Приклад API-запиту:
Тіло запиту:
{
"owner": 390,
"title": "Lead",
"comments": "qwerty"
}
Відповідь:
{
"id": 414,
"created_at": 1732627155,
"updated_at": 1732627155,
"title": "Lead",
"owner": 390,
"created_by": 1,
"changed_by": "",
"converted": false,
"contacts": "",
"companies": "",
"first_name": "",
"last_name": "",
"patronymic": "",
"company_name": "",
"position": "",
"utm_source": "",
"utm_medium": "",
"utm_campaign": "",
"utm_content": "",
"utm_term": "",
"messengers": "",
"phone": "",
"email": "",
"comments": "qwerty",
"source": "",
"lead_label": "",
"kanban_status": "IN_WORK",
"kanban_reason_id": "",
"closed_by": "",
"closed_at": "",
"first_closed_by": "",
"first_closed_at": "",
"kanban_stage_id": 1,
"table_name": "leads",
"new_kanban_stage_id": null,
"old_kanban_stage_id": null
}
Варто зазначити, що у випадку з CRM доступ ще й залежить від обсягу прав користувача в Просторі. Тобто ви повинні мати відповідні дозволи, наприклад, для створення лідів. Ну і звісно в налаштуваннях вебхука має бути наданий доступ до потрібного інструменту, тобто до CRM.
Приклад API-запиту, коли в кристувача не має відповідних доступів:
POST
Відповідь:
{
"errors": {
"text": [
"Access is denied!"
]
},
"status": true
}