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

Подпись запроса передаётся в заголовке X-Virazh-Signature в формате t=<таймстамп>, v1=<HMAC-SHA256>. Проверяйте подпись перед обработкой — без неё любой сторонний сервис сможет прислать вам поддельное событие.

Обзор событий

payment.succeeded

Отправляется, когда оплата билета, абонемента или заказа в магазине прошла успешно.

{
  "event": "payment.succeeded",
  "order_id": "ord_77a1",
  "amount": 800,
  "user_id": "usr_8f21c"
}

Поля payload

loyalty.status_changed

Отправляется при переходе пользователя на новый уровень программы лояльности.

{
  "event": "loyalty.status_changed",
  "user_id": "usr_8f21c",
  "from": "silver",
  "to": "gold"
}

Поля payload

broadcast.completed

Отправляется, когда рассылка полностью доставлена и собрана итоговая статистика.

{
  "event": "broadcast.completed",
  "broadcast_id": "bcast_9021",
  "delivered": 4310,
  "opened": 2144
}

Поля payload

ticket.refunded

Отправляется, когда заказ на билет или абонемент был возвращён — вручную или по правилам клуба.

{
  "event": "ticket.refunded",
  "order_id": "ord_77a1",
  "refunded_amount": 800
}

Поля payload

training.attendance_marked

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

{
  "event": "training.attendance_marked",
  "training_id": "tr_9911",
  "team_id": "team_2013",
  "present": 18,
  "total": 22
}

Поля payload

export.completed

Отправляется, когда асинхронная задача экспорта готова — вместо опроса /exports/{id} по таймеру.

{
  "event": "export.completed",
  "export_id": "exp_4471",
  "file_url": "https://files.virazh.io/exports/exp_4471.csv"
}

Поля payload

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

Если ваш сервер не ответил 200 OK в течение 5 секунд, платформа повторит доставку ещё до 5 раз с экспоненциальной задержкой (до 30 минут между попытками). Обработчик должен быть идемпотентным — один и тот же event_id может прийти дважды.

Полезно знать

• Возвращайте 200 OK сразу после сохранения события во внутреннюю очередь — тяжёлую обработку выполняйте асинхронно, иначе платформа посчитает доставку неуспешной по таймауту.
• Список подписанных URL и событий настраивается в админ-панели клуба, в разделе «Настройки → Интеграции».