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

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

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

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

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

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

События

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

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

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

Третья локерная подписка добавлена 21.09.2026. «Локер не используется более X дней» сообщает о бронях, которые держатся дольше указанного срока без единого открытия ячейки: в расчёт идут ячейки, забронированные раньше, чем «сегодня минус N дней», и ни разу не открытые за этот период. Дни считаются по часовому поясу офиса локера, а если своих настроек у офиса нет — по часовому поясу компании. Уходит одно письмо на подписку — тема «Неиспользуемые локеры», в теле список вида «локер, ячейка» со ссылками на раздел локеров; если подошедших ячеек нет, письма не будет. В отличие от соседнего события про длительность, это письмо приходит на каждом прогоне рассылки, пока ячейку не откроют. Подписка работает только при подключённой интеграции Pocket Lock: признак использования — факт открытия ячейки, а его даёт именно она.

Осторожно с буквой X в названиях локерных подписок. В названиях «Бронирование локера длится более 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.
• Неудачная доставка повторяется очередью — до 10 повторов с интервалом 10 секунд. Счётчик ошибок растёт на каждой попытке, включая повторы, поэтому одно недоставленное событие добавляет к счётчику 11. По достижении 100 неудач вебхук переводится в статус failed. Об этом уходит письмо — не «администраторам», а получателям активных подписок на событие system_warning («Проблемы синхронизаций»); если таких подписок нет, уведомления не будет. То же письмо приходит и когда подписку отключают вручную. Успешная доставка сбрасывает счётчик; ручное включение вебхука из статуса failed — тоже.
• Состояние вебхуков видно в External API > monitoring (категория webhooks) и на странице интеграций.

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

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