Справочник исходящих вебхуков

Исходящие вебхуки позволяют UnSpot уведомлять ваши системы о событиях в реальном времени: UnSpot отправляет HTTPS POST с JSON-телом на настроенный вами URL. Типичный сценарий — передача парковочных бронирований в систему СБ или управления шлагбаумом.

Настройка вебхука

Откройте Настройка > Интеграции > Исходящие подписки и нажмите «Добавить исходящую подписку». Обязательны название и событие; остальные поля формы зависят от типа события. Событие после сохранения не меняется — при редактировании подписки поле заблокировано.

• События типа API отправляют HTTPS-запрос: нужны URL получателя и пространства, к которым относится подписка. Доставляются только события выбранных пространств. Подписку с одинаковым событием и URL нельзя создать дважды.
• События типа email отправляют письмо. Получателя выбирают в поле «Получатель» из списка сотрудников — это внутренний активный пользователь UnSpot, а не произвольный адрес. Свободный ввод адреса из формы убран, подсказка поля — «Выберите получателя». Двух подписок на одно событие с одним и тем же получателем создать нельзя.
• Локерные email-события просят дополнительно пространства (мультивыбор, поле обязательное), а «Бронирование локера длится более X дней» — ещё и поле «Количество дней»: целое от 1 до 365, по умолчанию 1.

Что стало с прежними email-получателями. Раньше получателем был произвольный адрес электронной почты, теперь — ссылка на пользователя UnSpot. При переносе адрес сопоставляется с сотрудниками по почте без учёта регистра: нашёлся активный сотрудник — он становится получателем; не нашёлся, либо сотрудник в архиве, удалён или деактивирован — получатель остаётся пустым, а подписка переводится в состояние «Отключено». В списке подписок у такой строки вместо получателя стоит «Пользователь не указан», и включить её не удастся: сервер ответит ошибкой «Не удалось изменить статус подписки. Получатель не указан.» Чтобы вернуть подписку в работу, откройте «Изменить», выберите получателя и сохраните. Тот же механизм работает и дальше: если получателя архивируют, удалят или деактивирует синхронизация, подписка снова останется без получателя и отключится.

События

HTTPS-события (тип API):

Email-события (тип email) отправляют письмо выбранному получателю и HTTPS-запросов не делают — payload и правила доставки ниже к ним не относятся.

Две локерные подписки добавлены 07.09.2026. «Бронирование локера отменено» присылает письмо, когда бронь ячейки снимает политика «Горизонт бронирования»; уходит только по подпискам, у которых офис локера входит в выбранные пространства, а владелец брони получает своё отдельное письмо. «Бронирование локера длится более X дней» присылает одно письмо на подписку со списком всех подошедших ячеек.

Осторожно с формулировкой «длится более X дней». Письмо уходит в тот день, когда срок брони равен заданному количеству дней, а не каждый день, пока он превышен: сравнение идёт на равенство, а не на превышение. Буква X в названии подписки — часть подписи, а не подставляемое число. Дни считаются по часовому поясу офиса локера, а если у офиса своих настроек нет — по часовому поясу компании.

Формат payload

Все парковочные события используют один базовый payload; их различает поле action:

POST <ваш URL>
Content-Type: application/json

{
  "fullName": "Анна Иванова",
  "email": "anna.ivanova@example.com",
  "vehicleNumber": "А123ВС77",
  "vehicleModel": "Tesla Model 3",
  "start": "2026-07-08T09:00:00+00:00",
  "end": "2026-07-08T18:00:00+00:00",
  "office": "Штаб-квартира Москва",
  "parkingPlace": "P-12",
  "action": "Created",
  "bookingType": "Parking"
}

POST <ваш URL>
Content-Type: application/json

{
  "fullName": "Анна Иванова",
  "email": "anna.ivanova@example.com",
  "vehicleNumber": "А123ВС77",
  "vehicleModel": "Tesla Model 3",
  "start": "2026-07-08T09:00:00+00:00",
  "end": "2026-07-08T18:00:00+00:00",
  "office": "Штаб-квартира Москва",
  "parkingPlace": "P-12",
  "action": "Created",
  "bookingType": "Parking"
}

Доставка, таймауты и повторы

• Запросы отправляются как POST с Content-Type: application/json и таймаутом 240 секунд.
• Для подтверждения доставки ответьте любым статусом 2xx.
• Неудачные доставки увеличивают счётчик ошибок; доставка повторяется очередью. После 100 неудач подряд вебхук переводится в статус failed, администраторы получают уведомление. Успешная доставка сбрасывает счётчик.
• Состояние вебхуков видно в External API > monitoring (категория webhooks) и на странице интеграций.

Рекомендации по безопасности

• Стандартные запросы вебхуков идут без заголовка аутентификации — относитесь к URL endpoint’а как к секрету: используйте HTTPS и случайный сегмент пути (например, https://example.com/hooks/unspot-8f3a91).
• Валидируйте структуру payload и принимайте только ожидаемые поля.
• Для интеграции Claris UnSpot отправляет собственный Authorization: Bearer токен и расширенный payload — включайте опцию Claris только для этой системы. Состав этого payload и порядок настройки разобраны в статьях «Интеграция с Claris: как устроена» и «Настройка интеграции с Claris».