8cadd00d34
Created by Github action --------- Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: github-actions <github-actions@twenty.com>
87 lines
7.8 KiB
Plaintext
87 lines
7.8 KiB
Plaintext
---
|
||
title: Вебхуки
|
||
image: /images/docs/getting-started/webhooks.png
|
||
info: Discover how to use our Webhooks.
|
||
---
|
||
|
||
<Frame>
|
||
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
||
</Frame>
|
||
|
||
## Огляд
|
||
|
||
Вебхуки в Twenty доповнюють API, дозволяючи отримувати **повідомлення в реальному часі** у ваші власні застосунки, коли в CRM відбуваються певні події. Замість постійного опитування API щодо змін, ви можете налаштувати вебхуки, щоб Twenty **відправляв** дані у вашу систему щоразу, коли відбуваються певні події (наприклад, коли створюється новий запис або оновлюється існуючий). Це допомагає миттєво й ефективно синхронізувати зовнішні системи з Twenty.
|
||
|
||
За допомогою вебхуків Twenty відправлятиме HTTP POST-запит на URL, який ви вкажете, з подробицями про подію. You can then handle that data in your application (e.g., to update your external database, trigger workflows, or send alerts).
|
||
|
||
## Налаштування Вебхука
|
||
|
||
Для створення вебхука в Twenty скористайтеся налаштуваннями **API та Вебхуки** у вашому застосунку Twenty:
|
||
|
||
1. **Перейдіть у Налаштування:** у вашому застосунку Twenty перейдіть до **Налаштування → API та Вебхуки**.
|
||
2. **Створити Вебхук:** у розділі **Вебхуки** натисніть **+ Створити вебхук**.
|
||
3. **Введіть URL:** вкажіть кінцевий URL на вашому сервері, куди Twenty надсилатиме запити вебхука. Це має бути загальнодоступний URL, який здатний обробляти POST-запити.
|
||
4. **Зберегти:** натисніть **Зберегти**, щоб створити вебхук. Новий вебхук буде активований негайно.
|
||
|
||
You can create multiple webhooks if you need to send different events to different endpoints. Кожний вебхук є, по суті, підпискою на всі релевантні події (на даний час Twenty відправляє всі типи подій на вказану URL-адресу; фільтрація окремих типів подій може бути налаштована в інтерфейсі користувача). Якщо ви коли-небудь захочете видалити вебхук, ви можете зробити це на сторінці тих же налаштувань (виберіть вебхук та оберіть видалити).
|
||
|
||
## Події та Навантаження
|
||
|
||
Після налаштування вебхука Twenty відправлятиме HTTP POST-запит на вашу вказану URL-адресу щоразу, коли в даних вашої CRM відбувається подія-тригер. Загальні події, що запускають вебхуки, включають:
|
||
|
||
- **Створено запис:** наприклад, доданий нова особа (`person.created`), створена нова компанія (`company.created`), створено запис (`note.created`) тощо.
|
||
- **Оновлено запис:** наприклад, оновлено інформацію про наявну особу (`person.updated`), відредаговано запис компанії (`company.updated`) тощо.
|
||
- **Видалено запис:** наприклад, видалено особу або компанію (`person.deleted`, `company.deleted`).
|
||
- **Інші події:** якщо застосовно, інші події об'єктів або кастомні тригери (наприклад, якщо завдання або інші об'єкти оновлено, використовуватимуться аналогічні типи подій, як `task.created`, `note.updated` тощо).
|
||
|
||
Запит POST вебхука містить у своєму тілі JSON навантаження. Навантаження зазвичай містить принаймні дві речі: тип події та дані, що стосуються цієї події (часто запис, який був створений/оновлений). Наприклад, вебхук для нещодавно створеної особи може надіслати навантаження, як:
|
||
|
||
```
|
||
{
|
||
"event": "person.created",
|
||
"data": {
|
||
"id": "abc12345",
|
||
"firstName": "Alice",
|
||
"lastName": "Doe",
|
||
"email": "alice@example.com",
|
||
"createdAt": "2025-02-10T15:30:45Z",
|
||
"createdBy": "user_123"
|
||
},
|
||
"timestamp": "2025-02-10T15:30:50Z"
|
||
}
|
||
```
|
||
|
||
У цьому прикладі:
|
||
|
||
- `"event"` вказує, що сталося (`person.created`).
|
||
- `"data"` містить деталі нового запису (та ж інформація, яку ви отримаєте, якщо зробите запит на цю особу через API).
|
||
- `"timestamp"` - час, коли подія відбулася (в UTC).
|
||
|
||
Your endpoint should be prepared to receive such JSON data via POST. Зазвичай ви будете парсити JSON, дивитися на тип `"event"`, щоб зрозуміти, що сталося, і потім використовувати `"data"` відповідно (наприклад, створити новий контакт у вашій системі або оновити наявний).
|
||
|
||
**Примітка:** важливо відповісти **станом HTTP 2xx** від вашого кінцевого пункту вебхука для підтвердження успішного прийняття. Якщо відправник вебхука Twenty не отримає відповідь 2xx, це може вважати доставку невдалою. (В майбутньому логіка повторної спроби може спробувати повторно відправити не вдалі вебхуки, тому завжди прагніть повернути 200 OK якнайшвидше після обробки даних.)
|
||
|
||
## Валідація Вебхука
|
||
|
||
Для забезпечення безпеки ваших кінцевих точок вебхуків Twenty включає підпис у заголовку `X-Twenty-Webhook-Signature`.
|
||
|
||
Цей підпис є хешем HMAC SHA256 запиту навантаження, обчисленим з використанням вашого секретного ключа вебхука.
|
||
|
||
Щоб валідувати підпис, вам потрібно:
|
||
|
||
1. Конкатенувати таймштамп (зі заголовка `X-Twenty-Webhook-Timestamp`), двокрапку та рядок JSON навантаження
|
||
2. Обчислити хеш HMAC SHA256, використовуючи секретний ключ вебхука як ключ ()
|
||
3. Порівняти отриманий шістнадцятковий дайджест із заголовком підпису
|
||
|
||
Ось приклад на Node.js:
|
||
|
||
```javascript
|
||
const crypto = require("crypto");
|
||
const timestamp = "1735066639761";
|
||
const payload = JSON.stringify({...});
|
||
const secret = "your-secret";
|
||
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
|
||
const signature = crypto.createHmac("sha256", secret)
|
||
.update(stringToSign)
|
||
.digest("hex");
|
||
``` |