API hoba control: события объекта в вашей CRM

01 · подключение

Быстрый старт

1. 01

   Ключ от владельца

   Кабинет hoba control → «Интеграции» → «Создать ключ». Владелец выбирает объекты и может указать рядом номер клуба в вашей системе — он придёт в object.external_id. Ключ показывается один раз.

2. 02

   Ключ в каждом запросе

   Заголовок X-Partner-Key: <ключ> или Authorization: Bearer <ключ>. Только HTTPS.

3. 03

   События — опросом или вебхуком

   GET /v1/events с курсором либо адрес вебхука: его задаёт владелец в кабинете или вы сами через POST /v1/partners/webhook.

02 · формат

Событие

Один и тот же объект приходит в ответе GET /v1/events, GET /v1/events/{id} и в теле вебхука. Храните события по id: повтор не создаёт дубль, а версию с бо́льшим updated_at применяйте поверх старой.

{
  "id": "5b1f0c2e-8a47-4d1e-9c3a-2f6d8e7b4a10",
  "version": 1,
  "occurred_at": "2026-10-08T18:45:12+03:00",
  "received_at": "2026-10-08T18:45:13+03:00",
  "updated_at": "2026-10-08T18:45:28+03:00",
  "object": { "id": "3d7e2a91-6c0b-4f5e-8a12-9b4c7d1e0f23", "name": "Зал на Ленина 42", "external_id": "club_117" },
  "camera": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "name": "Вход" },
  "type": "tailgating",
  "type_label": "Проход по одному пропуску",
  "severity": "high",
  "details": { "persons_count": 2, "door_open_duration_sec": 8 },
  "verified": false,
  "revoked_at": null,
  "media": {
    "photo_url": "https://crm.hoba-control.ru/v1/media/5b1f0c2e-…/photo?token=…",
    "video_url": "https://crm.hoba-control.ru/v1/media/5b1f0c2e-…/clip?token=…",
    "video_ready": true,
    "expires_at": "2026-10-08T19:45:28+03:00",
    "available": true
  },
  "dashboard_url": "https://crm.hoba-control.ru/alerts/5b1f0c2e-8a47-4d1e-9c3a-2f6d8e7b4a10",
  "sandbox": false
}

03 · каталог

Типы событий

Актуальный список — GET /v1/event-types. Зарезервированные коды можно завести у себя заранее: когда сценарий заработает, события придут под этим кодом.

Часы работы для unauthorized владелец задаёт в кабинете hoba control — это не расписание занятий в вашей системе.

04 · справочник

Методы

Время в параметрах — ISO 8601. Используйте Z или закодируйте плюс в поясе как %2B: в адресе + превращается в пробел.

05 · синхронизация

Как забирать события

Надёжнее всего опрос по курсору. Начните с updated_since: в одном потоке придут и новые события, и изменения старых — отзыв, «Проверено», готовый клип. Сохраняйте next_cursor после каждого ответа и продолжайте с него.

# 1. Первый запрос — всё, что изменилось с нужного момента
GET /v1/events?updated_since=2026-10-28T00:00:00Z&limit=100

# 2. Дальше — только по курсору, раз в 30–60 секунд
GET /v1/events?cursor=<next_cursor из прошлого ответа>&limit=100

# has_more: true — сразу запросите следующую страницу.
# Пустой data — новых изменений нет, курсор остаётся прежним.

• Нужны только новые события?

  Начните с since — поток по времени приёма, без изменений старых.

• Последние 5 секунд в ответ не попадают

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

• Порядок вебхуков не гарантирован

  Ориентируйтесь на occurred_at и updated_at, а не на порядок прихода.

06 · персональные данные

Фото и видео

Медиа хранятся на устройстве в объекте и отдаются транзитом — копий на нашем сервере нет. Ссылки из события живут час (media.expires_at); свежие — в GET /v1/events/{id}. Ключ в заголовке для ссылки не нужен, её можно открыть в браузере менеджера.

Клип собирается около 10 секунд после события: пока video_ready равно false, ссылка отвечает 503, а когда клип готов, придёт event.updated.

07 · push

Вебхуки

POST с телом-событием на ваш адрес. Адрес — только HTTPS на публичном хосте; перенаправления не выполняются. Успех — любой ответ 2xx за 10 секунд.

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

Считайте подпись от сырого тела запроса, до разбора JSON. Запросы с временем, отличающимся от ваших часов больше чем на 5 минут, отбрасывайте.

import hashlib, hmac, time

def verify(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256)
    return hmac.compare_digest("sha256=" + mac.hexdigest(), signature)

const crypto = require('node:crypto');

function verify(secret, timestamp, rawBody, signature) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest('hex');
  return expected.length === signature.length
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Повторы

Если ответ не 2xx или его нет, повторяем: сразу → через 30 с → 2 мин → 10 мин → 1 ч → 6 ч. После шестой неудачи доставка получает статус dead и видна в GET /v1/deliveries; само событие можно забрать через GET /v1/events. Ответ 410 прекращает повторы сразу.

08 · справочник

Ошибки и лимиты