Вебхуки отправляют данные в ваши системы в реальном времени при возникновении событий в Twenty — опрос не требуется. Используйте их, чтобы поддерживать синхронизацию с внешними системами, запускать автоматизации или отправлять оповещения.
Создать Webhook
- Перейдите в Настройки → API и Вебхуки → Вебхуки
- Нажмите + Создать вебхук
- Введите URL вашего вебхука (должен быть общедоступным)
- Нажмите Сохранить
Вебхук активируется сразу и начинает отправлять уведомления.
Управление вебхуками
Изменить: Нажмите на вебхук → Обновите URL → Сохранить
Удалить: Нажмите на вебхук → Удалить → Подтвердить
События
Twenty отправляет вебхуки для следующих типов событий:
| Событие | Пример |
|---|
| Запись создана | person.created, company.created, note.created |
| Запись обновлена | person.updated, company.updated, opportunity.updated |
| Запись удалена | person.deleted, company.deleted |
Формат полезной нагрузки
Каждый вебхук отправляет HTTP 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"
}
| Поле | Описание |
|---|
событие | Что произошло (например, person.created) |
данные | Полная запись, которая была создана/обновлена/удалена |
метка времени | Когда произошло событие (UTC) |
Ответьте со статусом HTTP 2xx (200-299), чтобы подтвердить получение. Ответы вне диапазона 2xx фиксируются как ошибки доставки.
Валидация вебхуков
Twenty подписывает каждый запрос вебхука для обеспечения безопасности. Проверяйте подписи, чтобы убедиться в подлинности запросов.
Заголовки
| Заголовок | Описание |
|---|
X-Twenty-Webhook-Signature | Подпись HMAC SHA256 |
X-Twenty-Webhook-Timestamp | Метка времени запроса |
Шаги проверки
- Получите метку времени из
X-Twenty-Webhook-Timestamp
- Создайте строку:
{timestamp}:{JSON payload}
- Вычислите HMAC SHA256, используя секрет вашего вебхука
- Сравните с
X-Twenty-Webhook-Signature
Пример (Node.js)
const crypto = require("crypto");
const timestamp = req.headers["x-twenty-webhook-timestamp"];
const payload = JSON.stringify(req.body);
const secret = "your-webhook-secret";
const stringToSign = `${timestamp}:${payload}`;
const expectedSignature = crypto
.createHmac("sha256", secret)
.update(stringToSign)
.digest("hex");
const isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
Вебхуки vs рабочие процессы
| Метод | Направление | Сценарий использования |
|---|
| Вебхуки | OUT | Автоматически уведомлять внешние системы о любом изменении записи |
| Рабочий процесс + HTTP-запрос | OUT | Отправлять данные наружу с настраиваемой логикой (фильтры, преобразования) |
| Триггер вебхука в рабочем процессе | IN | Получать данные в Twenty из внешних систем |
