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

Вебхуки. Пользовательский интерфейс и управление.

Около 3 мин

Вебхуки. Пользовательский интерфейс и управление.

Вебхуки –это механизм автоматического уведомления сторонних систем о происходящих событиях в платформе Tangl.

В отличие от стандартных методов API, где стороннее приложение должно периодически запрашивать обновления, вебхуки работают по принципу Push-уведомлений: Tangl самостоятельно отправляет данные в систему пользователя немедленно в момент возникновения события.

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

Для перехода к странице управления вебхуками следует нажать кнопку шестеренки и выбрать пункт "Вебхуки".

Откроется страница управления вебхуками. Страница отображает уже созданные вебхуки в виде карточек, дает возможность ими управлять и создавать новые вебхуки.

Карточка вебхука содержит информацию об эндпоинте, выбранном действии триггера срабатывания, активности вебхука (активен или отключен) и кнопки действий:

  • "История доставок"– позволяет просмотреть историю доставок оповещений о событии;
  • "Редактировать" – позволяет внести изменения в настройки вебхука;
  • "Удалить" – для удаления вебхука.

Эндпоинт — это конкретный URL-адрес, который служит «точкой назначения» для передачи данных между системами. В случае с вебхуками он выступает в роли цифрового почтового ящика на сервере пользователя, куда Tangl отправляет уведомления о произошедших событиях. Чтобы интеграция работала, этот адрес должен быть доступен извне и настроен на прием и обработку входящих POST-запросов.

Для просмотра истории доставки необходимо нажать соответствующую кнопку "История доставок" на карточке вебхука.

Откроется страница истории доставок.

Создание вебхука

Для создания вебхука:

  1. Нажать кнопку "Вебхук +" в правом верхнем углу.

  2. Заполнить поля:

    • URL эндпоинта – указать адреса принимающего сервера, на который будут поступать POST-запросы;
    • Выбрать событие, инициирующее отправку данных:
      • model.uploaded – загружена BIM-модель;
      • analysis.approved – утвержден анализ в сервисе Value.

    События можно выбрать как по отдельности, так и все доступные.

  3. Нажать кнопку "Сохранить" для создания вебхука.

После завершения создания вебхука необходимо открыть форму его редактирования, скопировать сгенерированный секретный ключ и внести его в конфигурацию принимающего сервера или приложения-обработчика. Это необходимо для того, чтобы принимающий сервер мог успешно верифицировать подлинность входящих уведомлений от Tangl.

Редактирование вебхука

Для того чтобы открыть форму редактирования вебхука, необходимо нажать кнопку "Редактировать" в карточке вебхука.

Откроется форма редактирования, в которой можно:

  • внести изменения в адрес эндпоинта и выбранных событий срабатывания;

  • при помощи переключателя "Активен" отключить или включить вебхук;

  • сгенерировать новый секретный ключ.

Секретный ключ – это уникальный идентификатор безопасности, используемый для подтверждения подлинности передаваемых данных. Он выступает в роли связующего звена между платформой Tangl и принимающей стороной, позволяя серверу-обработчику удостовериться, что входящий запрос поступил от доверенного источника и не подвергался изменениям в процессе передачи.

Текущий секретный ключ, сгенерированный автоматически при создании вебхука, не отображается в поле, для его копирования в буфер обмена необходимо нажать кнопку "Копировать".

Для генерации нового секрета следует нажать кнопку "Перегенерировать секрет".

Новый секрет отобразится в поле, откуда его можно скопировать.

Секретный ключ необходимо сохранить в надёжном месте. Секретный ключ виден, пока окно редактирования остаётся открытым.

После внесения изменений необходимо нажать кнопку "Сохранить".

Удаление вебхука

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

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

Внимание! Удаление вебхука является необратимым действием. Если использование данного вебхука планируется возобновить в будущем, рекомендуется не удалять, а временно деактивировать его с помощью переключателя «Активен» в форме редактирования. Это позволит сохранить все настройки и секретный ключ для последующей работы.

Техническая реализация

Верификация по подписи

Проверка подлинности вебхука выполняется путем сравнения HMAC-SHA256 подписей:

  1. Платформа вычисляет хэш-сумму от тела (body) запроса, используя секретный ключ вебхука.
  2. Результат вычисления передается в заголовке X-Tangl-Signature в формате sha256=<значение_хэша>.
  3. Принимающая сторона должна самостоятельно вычислить аналогичный хэш от полученного исходного тела запроса (Raw Body) и сравнить его с пришедшим значением.

Подпись вычисляется как HMAC-SHA256(secret, raw_body) и кодируется в нижний hex. Получатель обязан вернуть HTTP 2xx в ответ на запрос, в противном случае доставка считается неудачной и будет инициирован повтор (retry).

Пример проверки на C#:

var key = Encoding.UTF8.GetBytes(secret);
var data = Encoding.UTF8.GetBytes(rawBody);
var expected = "sha256=" + Convert.ToHexString(HMACSHA256.HashData(key, data)).ToLowerInvariant();
var isValid = expected == request.Headers["X-Tangl-Signature"];

Повторные попытки отправки

Стандартный автоматический механизм повторов попыток отправки выглядит следующим образом:

  • 1-я попытка: немедленно при возникновении события.
  • 2-я попытка: через 1 минуту.
  • 3-я попытка: через 2 минуты.
  • 4-я попытка: через 4 минуты.
  • 5-я попытка: через 8 минут.
  • 6-я попытка: через 16 минут.

Каждая попытка отправки фиксируется в базе данных. Текущее состояние процесса можно отследить по следующим статусам:

  • Pending – Задача поставлена в очередь планировщика, выполнение сетевого запроса еще не началось;
  • Delivered – Успешное завершение. Принимающий сервер вернул HTTP-ответ в диапазоне 2xx;
  • Failed – Произошла ошибка (ответ 4xx/5xx или сетевой таймаут). Система фиксирует лог ошибки и планирует следующий повтор;
  • Exhausted – Все попытки (согласно лимиту MaxAttempts) исчерпаны, и каждая из них завершилась ошибкой. Дальнейшие действия по данной доставке прекращаются.

Формат и заголовки запроса

Каждое уведомление сопровождается набором служебных заголовков, необходимых для безопасности и идентификации события:

  • X-Tangl-Signature – Цифровая подпись сообщения (HMAC-SHA256). Формат: sha256=<hex>;
  • X-Tangl-Event – Тип события, например: model.uploaded или analysis.approved;
  • X-Tangl-Delivery – Уникальный ID попытки доставки (UUID) для проверки идемпотентности – отсечения дубликатов.

Пример полезной нагрузки (Payload):

{
 "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "event": "model.uploaded",
 "timestamp": "2024-01-01T12:00:00Z",
 "companyId": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
 "data": {
    "modelId": "5fa85f64-5717-4562-b3fc-2c963f66afa6",
    "modelName": "Building_A.ifc",
    "uploadedBy": "user@example.com"
 }
}
Default footer