Вебхуки

Вебхуки отправляют данные в ваши системы в реальном времени при возникновении событий в Twenty — опрос не требуется. Используйте их, чтобы поддерживать синхронизацию с внешними системами, запускать автоматизации или отправлять оповещения.

Создать Webhook

Перейдите в Настройки → API и Вебхуки → Вебхуки
Нажмите + Создать вебхук
Введите URL вашего вебхука (должен быть общедоступным)
Нажмите Сохранить

Вебхук активируется сразу и начинает отправлять уведомления.

Управление вебхуками

Изменить: Нажмите на вебхук → Обновите URL → Сохранить Удалить: Нажмите на вебхук → Удалить → Подтвердить

События

Twenty отправляет вебхуки для следующих типов событий:

Событие	Пример
Запись создана	`person.created`, `company.created`, `note.created`
Запись обновлена	`person.updated`, `company.updated`, `opportunity.updated`
Запись удалена	`person.deleted`, `company.deleted`

Все типы событий отправляются на URL вашего вебхука. Фильтрация событий может быть добавлена в будущих версиях.

Формат полезной нагрузки

Каждый вебхук отправляет 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 из внешних систем

Для получения внешних данных см. Настройка триггера вебхука.

Welcome

Core Concepts

Создать Webhook

Управление вебхуками

События

Формат полезной нагрузки

Валидация вебхуков

Заголовки

Шаги проверки

Пример (Node.js)

Вебхуки vs рабочие процессы

​Создать Webhook

​Управление вебхуками

​События

​Формат полезной нагрузки

​Валидация вебхуков

​Заголовки

​Шаги проверки

​Пример (Node.js)

​Вебхуки vs рабочие процессы

Создать Webhook

Управление вебхуками

События

Формат полезной нагрузки

Валидация вебхуков

Заголовки

Шаги проверки

Пример (Node.js)

Вебхуки vs рабочие процессы