Вебхуки Qronika

Подключение

1. Откройте «Вебхуки» в меню аккаунта и нужное пространство.
2. Создайте вебхук: название, публичный HTTPS-адрес и хотя бы одно событие.
3. Сохраните показанный один раз секрет в защищённом хранилище принимающей системы.
4. В карточке вебхука нажмите «Отправить тест». Обновите доставки и проверьте результат.

В карточке можно изменить название, адрес и события, отключить отправку, сменить секрет и повторить неудачную доставку. Отключённый вебхук можно удалить вместе с журналом доставок. Журнал хранится 90 дней.

События

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

При массовом переносе или удалении приходит событие для каждого изменённого QR. Перенос передаёт id и folder_id (или null вне папки); удаление — id. Повторный перенос в ту же папку не создаёт событие.

Формат запроса

Тело содержит ID события, тип, время создания в UTC и данные объекта. Заголовки: Content-Type: application/json, X-Qronika-Delivery (ID доставки), X-Qronika-Event (тип), X-Qronika-Timestamp (Unix timestamp попытки) и X-Qronika-Signature (подпись). Время и подпись формируются заново для каждой попытки.

{
    "id": "00000000-0000-4000-8000-000000000001",
    "type": "qr.created",
    "created_at": "2026-10-15T12:00:00+00:00",
    "data": {
        "qr_code": {
            "id": "00000000-0000-4000-8000-000000000002",
            "name": "Меню",
            "type": "url",
            "mode": "dynamic",
            "folder_id": null
        }
    }
}

qr.created содержит qr_code с полями id, name, type, mode, folder_id; qr.updated — id, name; qr.deleted — id. Создание и переименование папки передают folder: {id, name}, удаление — folder: {id}. События тиражей содержат batch: {id, status, created, errors}. Для bulk.cancelled передаются ID тиража и status: cancelled; счётчиков результата в этом событии нет. Тест передаёт data: {message: "Qronika webhook test"}.

Проверка подписи

Подпись имеет вид sha256=HEX. HEX — HMAC SHA-256 от строки timestamp + "." + исходное тело запроса с секретом вебхука. Проверяйте исходные байты до разбора JSON, ограничивайте возраст timestamp и сравнивайте через hash_equals.

 300) {
    http_response_code(400);
    exit;
}
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
// Атомарно сохраните ID события и поставьте обработку в свою очередь.
// Повтор уже сохранённого ID также должен завершаться успешным ответом.
http_response_code(204);

Сохраняйте ID события или доставки с уникальным ограничением и обрабатывайте повтор идемпотентно. Доставка может повториться, например если событие принято, но ответ не дошёл до Qronika. Порядок доставки событий не гарантируется.

Ответы и повторы

HTTP-ответ 2xx означает успех, если передача завершилась без сетевой ошибки. При таймауте, обрыве или превышении лимита ответа доставка повторится, даже если заголовки 2xx уже получены. Ответьте быстро, например 204 No Content, а длительную работу выполняйте в своей очереди. Таймаут соединения — 3 секунды, запроса — 8 секунд. Тело ответа получателя ограничено 64 КиБ; возвращайте короткий ответ. Перенаправления не выполняются. Локальные и приватные адреса запрещены.

При ошибке предусмотрены пять повторов: через 1 минуту, 5 минут, 30 минут, 2 часа и 12 часов после предыдущей попытки. После шестой неудачной попытки автоматические повторы прекращаются и приходит уведомление. В журнале доступны статус, число попыток, HTTP-ответ, ошибка, следующая попытка и JSON. Можно поставить неудачную доставку в очередь вручную, сохранив ID и тело.

Если отправка приостановлена

Перед каждой попыткой проверяются текущий тариф, доступность пространства и владельца, а также управляющее участие создателя вебхука. При потере доступа доставка откладывается без расходования попытки; после восстановления условия проверяются снова. Отключённый вебхук не отправляет запросы до включения. Очередь и журнал не хранятся бессрочно: срок хранения событий — 90 дней.

Статус failed означает неудачную попытку с ожидающим повтором, cancelled — прекращение автоматических попыток. Ручной повтор доступен для активного вебхука при подходящем тарифе. Удаление вебхука удаляет и его журнал; экспортируйте нужные сведения до удаления.

Смена адреса и секрета

Новый адрес применяется ко всем следующим попыткам, включая очередь. После смены секрета новые попытки подписываются новым секретом; старый сразу перестаёт использоваться. Обновите секрет в принимающей системе. Если требуется согласовать переключение, предварительно отключите вебхук, смените настройки и включите его после настройки получателя.