Вебхуки. Як це працює?

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

Вебхуки в Uspacy – це спосіб автоматизувати роботу у Просторі. А саме автоматично «сигналізувати» про певні події, які відбуваються в Uspacy, стороннім сервісам. Або навпаки, дозволяють зовнішнім системам відправляти через спеціальну URL-адресу дані в Простір, де потім на їх основі виконати певну дію.

Саме тому в Uspacy можна працювати як з вихідними вебхуками, так і з вхідними.

Уся робота відбувається на однойменній сторінці Простору. Щоб перейти на неї потрібно розгорнути розділ Автоматизація.

Вихідні

Як створити новий вихідний вебхук?

Щоб зробити це, натисніть на відповідну кнопку.

Відкриється вікно, де потрібно бути заповнити всі поля. Вибрати що саме та з яким об’єктом буде відбуватися, щоб на основі цих змін надіслати дані за межі Uspacy стороннім сервісам.

Подія – що саме повинно статися. Тобто, вебхук відпрацює, коли буде створено, змінено, видалено об’єкт чи змінено етап для нього.

Об’єкт події – те, з чим відбувається взаємодія. Тобто вебхук відпрацює, коли певну сутність, а саме лід, угоду, контакт, компанію, справу, завдання, допис чи коментар буде створено, змінено, видалено чи змінено етап для них.

Активність – забезпечує роботу вебхука, після його підтвердження.

Кінцева точка за межами Uspacy – URL-адреса, на яку потрібно надсилати дані. Там розробник розміщує спеціальний код, який буде обробляти вхідні запити (повідомлення).

Коли всі поля заповнені, натисніть Створити.

Вебхук одразу буде додано до загального переліку. Спочатку він отримає статус Непідтверджений. Тому, щоб вебхук почав коректно працювати потрібно його підтвердити. ⬇️

Як підтвердити вихідний вебхук?

Після створення вебхуку Uspacy надішле POST-запит на вашу URL-адресу кінцевої точки з підтверджувальним посиланням.

А ваш сервер повинен прийняти цей запит, видобути це посилання та перейти по ньому.

Готово ✅

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

Корисні посилання та поради

Для підтвердження та обробки вхідних повідомлень можна використовувати готові хендлери Amazon SNS для різних мов та фреймворків.

Приклад повідомлення про подію

{

"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-запиту:

GET

https://yourdomain.uspacy.ua/company/v1/incoming_webhooks/run/gbkn4xrF0b8e4W86jQivcdKCJWvWW7qO/tasks/v1/tasks/816

Відповідь:

{

"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-запиту:

POST https://yourdomain.uspacy.ua/company/v1/incoming_webhooks/run/gbkn4xrF0b8e4W86jQivcdKCJWvWW7qO/crm/v1/entities/leads

Тіло запиту:

{

"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

https://yourdomain.uspacy.ua/company/v1/incoming_webhooks/run/gbkn4xrF0b8e4W86jQivcdKCJWvWW7qO/crm/v1/entities/leads

Відповідь:

{

"errors": {

"text": [

"Access is denied!"

]

},

"status": true

}