Перейти к основному содержанию
Header

​
Обзор

Вебхуки в Twenty дополняют API, позволяя получать уведомления в режиме реального времени в ваши собственные приложения, когда в вашей CRM происходят определённые события. Вместо того чтобы постоянно опрашивать API на предмет изменений, вы можете настроить вебхуки так, чтобы Twenty отправлял данные в вашу систему, когда происходят определённые события (например, когда создаётся новая запись или обновляется существующая запись). Это помогает мгновенно и эффективно синхронизировать внешние системы с Twenty. С помощью вебхуков, Twenty отправит HTTP POST запрос на указанный вами URL, содержащий детали события. Затем вы можете обрабатывать эти данные в вашем приложении (например, для обновления внешней базы данных, запуска рабочих процессов или отправки предупреждений).

​
Настройка вебхука

Чтобы создать вебхук в Twenty, используйте настройки API & Webhooks в вашем приложении Twenty:
  1. Перейдите в Настройки: В вашем приложении Twenty перейдите в Настройки → API & Webhooks.
  2. Создать вебхук: В разделе Webhooks нажмите на + Создать вебхук.
  3. Введите URL: Укажите конечный URL на вашем сервере, куда вы хотите, чтобы Twenty отправлял запросы вебхука. Это должен быть общедоступный URL, который может обрабатывать POST-запросы.
  4. Сохранить: Нажмите Сохранить, чтобы создать вебхук. Новый вебхук будет активирован немедленно.
Вы можете создать несколько вебхуков, если вам нужно отправлять разные события на разные конечные точки. Каждый вебхук по сути является подпиской на все соответствующие события (в настоящее время Twenty отправляет все типы событий на указанный URL; фильтрация определённых типов событий может быть настроена в интерфейсе). Если вам когда-либо понадобится удалить вебхук, вы можете удалить его на той же странице настроек (выберите вебхук и выберите удалить).

​
Events and Payloads

Как только вебхук настроен, Twenty отправит HTTP POST запрос на указанный URL всякий раз, когда в данных CRM произойдёт триггерное событие. Общие события, вызывающие вебхуки, включают:
  • Запись создана: например, добавлен новый человек (person.created), создана новая компания (company.created), создана новая заметка (note.created) и т.д.
  • Запись обновлена: например, обновлена информация существующего человека (person.updated), изменена запись компании (company.updated) и т.д.
  • Запись удалена: например, удалён человек или компания (person.deleted, company.deleted).
  • Другие события: если применимо, другие события объектов или пользовательские триггеры (например, если обновляются задачи или другие объекты, использовались бы аналогичные типы событий, такие как task.created, note.updated и др.).
The webhook POST request contains a JSON payload in its body. Payload обычно включает как минимум две вещи: тип события и данные, связанные с этим событием (часто это запись, которая была создана/обновлена). Например, вебхук для недавно созданного человека может отправить такой payload: 
{
  "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).
Ваш конечный пункт должен быть готов принимать такие данные JSON через POST. Обычно вы будете разбирать JSON, смотреть на тип "event", чтобы понять, что произошло, а затем использовать "data" соответствующим образом (например, создать новый контакт в вашей системе или обновить существующий). Примечание: Важно ответить 2xx HTTP статусом с вашего конечного пункта вебхука для подтверждения успешного получения. Если отправитель вебхука в Twenty не получит ответ 2xx, он может считать доставку неудачной. (В будущем логика повторной попытки может попытаться переслать неудачные вебхуки, поэтому всегда стремитесь вернуть 200 OK как можно быстрее после обработки данных.)

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

Чтобы обеспечить безопасность ваших конечных точек вебхуков, Twenty включает подпись в заголовке X-Twenty-Webhook-Signature. Эта подпись является HMAC SHA256 хэшом payload запроса, вычисленным с использованием вашего секрета вебхука. Чтобы проверить подпись, вам нужно:
  1. Конкатенировать временную метку (из заголовка X-Twenty-Webhook-Timestamp), двоеточие и строку JSON payload
  2. Вычислите HMAC SHA256 хэш, используя ваш секрет вебхука в качестве ключа ()
  3. Сравните полученный шестнадцатеричный дайджест с заголовком подписи
Вот пример на Node.js: 
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");