Webhook Targets

Seatmap.pro может уведомлять ваши системы об изменениях площадок, схем и карт мест. На этой странице описано, каким должен быть адрес вебхука и что происходит при неудачной доставке.

События

Событие	Когда отправляется
`venue.created`	Создана площадка.
`venue.updated`	Изменена площадка.
`venue.deleted`	Удалена площадка.
`schema.created`	Создана схема.
`schema.updated`	Изменена схема.
`schema.deleted`	Удалена схема.
`seatmap.stored`	Сохранена карта мест.

Требования к адресу

Breaking: начиная с 1.70.0 адрес вебхука должен быть публичным HTTPS-адресом. Адрес, не удовлетворяющий обоим условиям, отклоняется при сохранении, а любая доставка на него записывается с типом ошибки TARGET_NOT_ALLOWED.

Адрес принимается, если:

URL — корректный URI с хостом.
Схема — https. Незашифрованный http отклоняется.
Все адреса, в которые разрешается хост, публично маршрутизируемы.

Хост отклоняется, если любой из его адресов относится к loopback, link-local, site-local (частные диапазоны вроде 10.0.0.0/8, 172.16.0.0/12 и 192.168.0.0/16), multicast, CGNAT или иным образом зарезервирован. Отклоняются также IPv6-адреса unique-local и IPv4-mapped IPv6-адреса, у которых заблокирован лежащий в основе IPv4-адрес. Хост, который вообще не разрешается, тоже отклоняется.

Если ваш эндпоинт не публичный

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

Self-hosted установки, которым действительно нужна доставка внутри собственной сети, могут задать сервису редактора seatmap.webhooks.allow-private-targets со значением true. Это выключает проверку адресов, поэтому включайте эту настройку только тогда, когда весь сетевой путь находится под вашим контролем.

Повторы доставки

Неудачная доставка повторяется с экспоненциальной задержкой, по умолчанию три раза. Значения по умолчанию:

Параметр	По умолчанию	Что означает
`timeoutMs`	`30000`	Таймаут одной попытки.
`maxRetries`	`3`	Число повторов после первой попытки.
`backoffInitialMs`	`1000`	Задержка перед первым повтором.
`backoffMultiplier`	`2.0`	Множитель для каждой следующей задержки.
`retryOnHttpStatuses`	`500, 502, 503, 504`	Коды, при которых доставка повторяется.
`skipRetryOnHttpStatuses`	`400, 401, 403, 404`	Коды, которые считаются окончательными.

Таймауты, сетевые ошибки и ошибки соединения повторяются. Ошибка TARGET_NOT_ALLOWED не повторяется: адрес некорректен, и ожидание не поможет. После последнего повтора событие попадает в список недоставленных, а не пропадает молча.

Что сохраняется в попытке доставки

В каждой попытке фиксируются статус, тип ошибки и фрагмент тела ответа, чтобы можно было понять причину сбоя, не встраивая логирование в собственный эндпоинт.

Заголовки ответа, несущие учётные данные, сохраняются как [redacted]: authorization, proxy-authorization, set-cookie, set-cookie2, www-authenticate, proxy-authenticate и x-amz-security-token. Если ваш эндпоинт возвращает токен в одном из этих заголовков, в журнал доставок он не попадёт.