Вебхуки

Исходящие вебхуки позволяют получать уведомления HTTP POST в реальном времени при возникновении событий в вашем проекте. Pro

Обзор

Вебхуки доставляют JSON-полезную нагрузку на любой HTTPS-эндпоинт, который вы настраиваете, когда происходит определённое событие в вашем проекте. Каждый вебхук может подписаться на одно или несколько следующих событий:

Вебхуки привязаны к отдельным проектам. Каждый проект имеет собственный набор эндпоинтов вебхуков с независимыми конфигурациями и секретами подписи.

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

1. Перейдите на страницу Интеграции вашего проекта
2. Прокрутите до раздела Исходящие вебхуки
3. Нажмите Добавить вебхук
4. Введите URL вашего эндпоинта (в продакшене должен быть HTTPS)
5. Выберите события, на которые хотите подписаться
6. Нажмите Сохранить

После сохранения секрет подписи отображается один раз. Скопируйте его немедленно — его невозможно получить позже. Вы можете перегенерировать его в любое время из меню действий вебхука.

Проверка подписей вебхуков

Каждая доставка вебхука включает заголовок X-SupDesk-Signature, содержащий подпись HMAC-SHA256 тела запроса. Для проверки вебхука:

1. Вычислите HMAC-SHA256(ваш_секрет_подписи, тело_запроса)
2. Сравните результат с шестнадцатеричным значением в заголовке X-SupDesk-Signature (после префикса sha256=)
3. Используйте сравнение постоянного времени для предотвращения атак по времени

Node.js

import { createHmac, timingSafeEqual } from "crypto";
 
function verifyWebhook(secret, body, signature) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const sig = signature.replace("sha256=", "");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Python

import hmac
import hashlib
 
def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    sig = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, sig)

Ruby

require "openssl"
 
def verify_webhook(secret, body, signature)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, body)
  sig = signature.sub("sha256=", "")
  Rack::Utils.secure_compare(expected, sig)
end

Тестирование вебхука

Нажмите кнопку Тест рядом с вебхуком, чтобы отправить тестовую полезную нагрузку на его эндпоинт. Тестовая нагрузка содержит "event": "test" и поле data.message. Используйте инструмент вроде webhook.site  для проверки доставленного запроса.

Журнал доставки

Журнал доставки показывает последние 50 попыток доставки для каждого вебхука, включая:

• Событие — какое событие было доставлено
• Статус — success или failed
• Код ответа — HTTP-код статуса от эндпоинта
• Попытки — количество попыток доставки (включая повторные попытки)
• Время — когда была предпринята попытка доставки

Поведение повторных попыток

При неудачной доставке вебхука (ответ 5xx или сетевой тайм-аут) SupDesk повторяет до 3 раз с экспоненциальной задержкой:

Ошибки клиента (4xx) не повторяются — они указывают на постоянную проблему с конфигурацией эндпоинта.

Требования к тарифу

Исходящие вебхуки доступны на тарифах Pro и Team.