Введение

Если вы когда-нибудь настраивали интеграцию между двумя сервисами — например, чтобы данные из одной системы автоматически попадали в CRM или Google Таблицы — вы наверняка сталкивались с термином «вебхук» (webhook). Это одна из тех технологий, которые незаметно лежат в основе большей части современной автоматизации: от уведомлений в Slack до синхронизации заказов в интернет-магазине.

В этой статье разберём, что такое вебхуки простыми словами, чем они отличаются от обычных запросов к API, и как на практике настроить получение уведомлений о переходах по коротким ссылкам с помощью вебхуков в Lix.li.

Что такое вебхук простыми словами

Вебхук — это способ автоматической передачи данных от одного сервиса к другому в момент, когда происходит определённое событие. Вместо того чтобы ваша система постоянно спрашивала: «Что-нибудь новое появилось?» — сервис сам присылает данные на ваш сервер, как только событие произошло.

Проще всего понять разницу через аналогию с почтой:

Обычный API-запрос — это как самому регулярно бегать до почтового ящика и проверять, не пришло ли письмо.
Вебхук — это как подписаться на доставку: письмо само приходит к вам домой, как только оно готово.

Технически вебхук — это обычный HTTP-запрос (чаще всего POST), который один сервер отправляет на заранее указанный адрес (URL) на другом сервере, когда происходит нужное событие — например, оплата заказа, изменение статуса задачи или, как в случае с Lix.li, переход по короткой ссылке.

Зачем нужны вебхуки

Вебхуки решают одну конкретную проблему: как получать актуальные данные без постоянного «опроса» (polling) внешнего сервиса.

Без вебхуков, чтобы узнать о новых событиях, пришлось бы регулярно отправлять запросы к API — раз в минуту, раз в пять минут — и каждый раз проверять, не появилось ли что-то новое. Это создаёт лишнюю нагрузку на оба сервера и всегда добавляет задержку между самим событием и моментом, когда вы о нём узнали.

Вебхуки переворачивают эту логику: сервис сам уведомляет вас, когда что-то произошло. Это особенно полезно для:

Автоматизации бизнес-процессов — например, автоматической записи новых лидов в CRM.
Интеграции с аналитикой — передачи данных о переходах в собственную систему учёта.
Ботов и уведомлений — отправки события в Telegram-бота или Slack-канал команды.
Синхронизации данных — обновления Google Таблиц, дашбордов или внутренних систем в реальном времени.

Как работают вебхуки на примере Lix.li

В Lix.li вебхуки позволяют получать информацию о переходах по вашим коротким ссылкам прямо на ваш сервер — автоматически, без необходимости постоянно опрашивать API сервиса. Это удобно, если вы хотите заводить события в свою CRM, систему аналитики, Google Таблицы, Telegram-бота или любую другую систему автоматизации.

Как это устроено

Переходы по ссылкам не отправляются по одному, а накапливаются и передаются пачками — раз в несколько минут. Это снижает нагрузку и на ваш сервер, и на сервер Lix.li.
Доставка происходит почти в реальном времени, но не мгновенно — вебхуки предназначены для сценариев, где приемлема задержка в несколько минут, а не для мгновенной реакции на каждый клик.
Гарантия доставки построена по принципу «хотя бы один раз»: если при отправке произошёл сетевой сбой, пачка данных может прийти повторно. Поэтому у каждого события есть уникальный идентификатор event_id, по которому нужно исключать дубликаты на своей стороне.

Настройка вебхука в личном кабинете

Функция вебхуков доступна на тарифе Premium. Настройка занимает несколько шагов:

Откройте раздел «Вебхуки» в личном кабинете и нажмите «Добавить».
Укажите:
- URL приёмника — адрес на вашем сервере, который будет принимать запросы (например, https://api.вашсайт.com/webhooks/lix);
- область действия — присылать события по всем ссылкам, по конкретной группе ссылок или только по одной ссылке;
- нужно ли включать IP-адрес посетителя в данные события (по умолчанию — отключено, так как это персональные данные).
Сразу после создания вебхука вам покажут секретный ключ, который отображается только один раз — обязательно сохраните его, он нужен для проверки подлинности входящих запросов.
Нажмите «Тест» — сервис отправит тестовое событие и покажет, ответил ли ваш сервер корректно.

Процесс создания веб-хуков и список настроенных веб-хуков на панели управления Lix.li.

Что приходит на ваш сервер

Каждый запрос отправляется методом POST с телом в формате application/json. Помимо самих данных, запрос содержит несколько служебных заголовков:

Заголовок	Назначение
`X-Lix-Signature`	Подпись тела запроса в формате `sha256=` — для проверки подлинности.
`X-Lix-Timestamp`	Время отправки запроса в формате Unix-времени.
`X-Lix-Delivery`	Уникальный идентификатор доставки.
`User-Agent`	Значение `Lix-Webhooks/1.0`.

Тело запроса содержит саму пачку событий:

{
  "delivery_id": "0f3b9c2e-6a1d-4e88-9d5a-2f8c1b7a4e10",
  "event_type": "redirects.batch",
  "sent_at": "2026-06-01T12:05:00Z",
  "window": {
    "from": "2026-06-01T12:00:00Z",
    "to":   "2026-06-01T12:03:30Z"
  },
  "count": 2,
  "truncated": false,
  "events": [
    {
      "event_id":   "2ef7bde608ce5404e97d5f042f95f89f1c232871",
      "link_id":    12345,
      "datetime":   "2026-06-01T12:01:00Z",
      "country":    "US",
      "city":       "Boston",
      "browser":    "Chrome",
      "os":         "Windows",
      "device":     "Desktop",
      "ref_domain": "google.com",
      "group_id":   null,
      "is_bot":     false
    }
  ]
}

Каждое событие внутри пачки содержит идентификатор ссылки, время перехода в UTC, страну, город, браузер, операционную систему, тип устройства, домен-источник перехода, ID группы (если задана), а также признак бота. IP-адрес посетителя добавляется в данные, только если вы явно включили эту опцию при настройке вебхука.

Если событий накопилось очень много, пачка может быть помечена флагом truncated: true — это означает, что часть данных придёт следующей доставкой, и ничего не теряется.

Как проверить подлинность запроса

Поскольку URL вашего сервера технически может получить запрос откуда угодно, важно убедиться, что запрос действительно пришёл от Lix.li, а не является подделкой. Для этого используется подпись в заголовке X-Lix-Signature.

Принцип проверки: вы берёте «сырое» (необработанное) тело запроса, вычисляете от него HMAC-SHA256 с использованием вашего секретного ключа, и сравниваете результат с тем, что пришло в заголовке. Сравнение должно выполняться безопасным способом (constant-time), чтобы исключить атаки по времени сравнения.

Пример на PHP:

$raw    = file_get_contents('php://input');
$secret = 'ваш_secret';

$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_LIX_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

Пример на Node.js (Express):

const crypto = require('crypto');

// важно получить сырое тело: app.use(express.raw({ type: 'application/json' }))
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
const got = req.header('X-Lix-Signature') || '';

if (expected.length !== got.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got))) {
  return res.sendStatus(401);
}

Пример на Python (Flask):

import hmac, hashlib

raw = request.get_data()  # сырые байты
expected = 'sha256=' + hmac.new(secret.encode(), raw, hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, request.headers.get('X-Lix-Signature', '')):
    return '', 401

Требования к серверу-приёмнику

Чтобы вебхуки работали стабильно, ваш сервер должен соответствовать нескольким правилам:

Отвечать кодом 2xx. Любой другой код или превышение времени ожидания считается неуспехом, и доставка будет повторена.
Отвечать быстро. На ответ отводится всего несколько секунд — не стоит обрабатывать данные синхронно прямо в обработчике запроса. Правильный подход: быстро сохранить полученные данные (например, в очередь или базу), вернуть 2xx, а уже затем обработать их отдельно.
Исключать дубликаты по event_id. Из-за механизма повторной доставки одно и то же событие иногда может прийти дважды.
Быть идемпотентным. Повторная обработка одной и той же пачки не должна приводить к некорректным данным на вашей стороне.
Обязательно проверять подпись на каждом входящем запросе.
Использовать HTTPS. Локальные и внутренние адреса для приёма вебхуков не поддерживаются.

Что происходит при сбоях

Если ваш сервер не отвечает кодом 2xx, Lix.li повторяет попытку доставки с постепенно увеличивающейся паузой между попытками. Если приёмник долгое время не отвечает вовсе (много неудачных попыток подряд), вебхук автоматически ставится на паузу, чтобы избежать бессмысленных отправок в никуда. Информация об этом отображается в журнале доставок в личном кабинете, и после исправления проблемы на своей стороне вы можете включить вебхук обратно.

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

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

Тест — отправить одно тестовое событие и сразу увидеть результат: успех или конкретный код ответа сервера.
Пауза / включение — временно остановить или возобновить доставку событий.
Смена секретного ключа — сгенерировать новый ключ вместо старого; старый перестаёт действовать мгновенно, поэтому важно сразу обновить его и на своей стороне.
Удаление — полностью убрать вебхук.
Журнал доставок — история последних отправок с указанием статуса, HTTP-кода ответа, количества событий в пачке и времени отправки.

Часто задаваемые вопросы

Как быстро приходят события? Пачками, примерно раз в несколько минут, с небольшой задержкой на обработку. Это не мгновенная push-доставка, а near-real-time сценарий.

Может ли одно и то же событие прийти дважды? Да, при повторной доставке после сетевого сбоя. Именно поэтому важно дедуплицировать события по полю event_id на своей стороне.

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

Что происходит при очень большом объёме трафика? Если событий за один интервал накопилось слишком много, пачка помечается флагом truncated: true, а оставшаяся часть данных приходит со следующей доставкой — потери данных при этом не происходит.

Обязательно ли использовать HTTPS? Да, адрес приёмника должен начинаться с https://. Локальные и внутренние адреса не принимаются.

Можно ли получать события только по одной ссылке или группе ссылок? Да, при создании вебхука можно выбрать область действия «Одна ссылка» или «Группа» вместо всех ссылок аккаунта.