Вебхук — это способ автоматически отправлять уведомления во внешний сервис при наступлении определенного события.
Вместо того чтобы вручную проверять изменения в панели управления или периодически опрашивать API, система сама отправляет POST-запрос на указанный вами URL.
Такой формат удобно использовать для интеграции с:
- внутренними сервисами;
- корпоративными чатами;
- системами мониторинга;
- helpdesk-платформами;
- собственными сценариями автоматизации.
Например, вы можете автоматически получать уведомления о списаниях, окончании срока действия SSL-сертификата или событиях безопасности.
Как работают уведомления через вебхуки
После настройки вебхука при наступлении выбранного события сервис отправляет HTTP POST-запрос на указанный URL-адрес.
Для успешной доставки обработчик должен:
- быть доступен из интернета по публичному URL;
- иметь валидный SSL-сертификат;
- принимать POST-запросы;
- возвращать HTTP-код 2xx.
Если конечная точка недоступна или возвращает ошибку, уведомление считается недоставленным.
Для аккаунта можно создать до 20 вебхуков.
Для каждого вебхука отдельно выбираются категории уведомлений:
- Безопасность
- Биллинг
- Облачные сервисы
- Базы данных
- S3
- Лицензии
- Домены
- SSL-сертификаты
- Идеи и комментарии
- AI-агенты
- Остальное
Это позволяет направлять разные типы событий в разные системы. Например, уведомления о биллинге можно направлять в бухгалтерию, события безопасности — в SIEM-систему, а инфраструктурные уведомления — в чат команды DevOps.
Настройка вебхуков
Для настройки вебхуков перейдите в раздел «Уведомления» панели управления аккаунтом и нажмите кнопку «Настроить» напротив строки «Вебхуки».
В открывшемся окне укажите:
- имя вебхука;
- URL обработчика;
- при необходимости — ключ подписи;
- категории уведомлений.
Для проверки адреса можно использовать кнопку «Отправить тест».
Ключ для подписи заголовков
Ключ подписи используется не для шифрования данных, а для проверки подлинности запроса. Без проверки любой пользователь может отправить POST-запрос на ваш URL, имитируя уведомление. Если на такие события завязаны автоматические действия, злоумышленник сможет запускать их вручную.
Чтобы избежать этого, запрос подписывается с использованием вашего секретного ключа.
В результате вместе с уведомлением передается специальный заголовок с цифровой подписью. Ваш обработчик может проверить ее и убедиться, что запрос действительно отправлен сервисом, а содержимое не было изменено.
В качестве ключа можно использовать любую строку, однако рекомендуется использовать случайное значение достаточной длины.
Для генерации ключа можно выполнить команду:
openssl rand -base64 32
Пример результата:
K1nL9sVx3Qp8mRzY2uT7cAaB0eHkLmNoPqRsTuVw=
Пример использования подписи
При получении вебхук-запроса необходимо взять тело запроса в исходном виде, вычислить для него подпись с использованием заданного ключа и сравнить результат со значением из заголовка X-Timeweb-Cloud-Signature. Если значения совпадают, запрос можно считать подлинным.
Важно использовать тело запроса в исходном строковом виде. Даже незначительные изменения форматирования JSON (например, пробелы или переносы строк) приведут к несовпадению подписи.
Пример проверки подписи на Node.js:
import crypto from 'crypto';
function verifyWebhookSignature(rawBody, secret, signatureHeader) {
if (!signatureHeader?.startsWith('sha256=')) {
return false;
}
const receivedSignature = signatureHeader.slice('sha256='.length);
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(rawBody, 'utf8')
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(receivedSignature, 'hex'),
Buffer.from(expectedSignature, 'hex')
);
}
const rawBody = '{"event_group":"cloud_servers","event":"server_cloning","created_at":"2026-04-23T14:40:46.339Z","account_id":"nt94542","data":{"vds_id":7665237}}';
const secret = '9BjJ3WUEZNnNF/0fS969BC7Hqo66ro/uen5pTAQIh6I=';
const signature = 'sha256=34f1ff761e625cb12b36b1775ebcc7fd77d93888876472542c93744e99f09bb2';
console.log(verifyWebhookSignature(rawBody, secret, signature));
В примере вычисленная подпись совпадает со значением из заголовка, значит запрос не был изменен и действительно отправлен сервисом. Любое изменение тела запроса или использование другого ключа приведет к несовпадению подписи и результату false.
Формат событий вебхуков
Каждое уведомление отправляется в виде JSON-объекта. Все события содержат общие обязательные поля верхнего уровня:
{
"event_group": "security",
"event": "db_deletion_confirmation",
"created_at": "2026-02-16T10:21:30.000Z",
"account_id": 42,
"data": {}
}
Где:
event_group— группа события;event— конкретный тип события;created_at— дата и время создания уведомления в формате ISO 8601;account_id— идентификатор аккаунта;data— объект с дополнительными данными события.
Содержание data зависит от типа уведомления.
Описание событий каждой группы доступно в отдельных статьях: