Webhooks

Webhooks позволяют получать уведомления о событиях в реальном времени. Вместо периодического опроса API, GuestMe отправляет HTTP-запросы на ваш URL при каждом изменении данных.

Создание webhook

Параметры

Поле	Тип	Обязательное	Описание
url	string	да	URL для получения уведомлений (HTTPS рекомендуется)
token	string	нет	Токен для авторизации (передаётся в заголовке вместе с authorizationHeaderPrefix)
authorizationHeaderPrefix	string	нет	Префикс перед токеном в заголовке Authorization. По умолчанию не ставится. Максимум 20 символов. Например, если указать Bearer, заголовок будет Authorization: Bearer ваш_токен
events	array	нет	Типы событий: CREATE, UPDATE, DELETE. Если не указаны — все события
entities	array	нет	Типы сущностей: RESTAURANT, BOOKING. Если не указаны — все сущности

curl -X POST "https://backend.guestme.ru/api/v1/external/webhook" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/guestme",
    "token": "your_secret_token",
    "authorizationHeaderPrefix": "Bearer",
    "events": ["CREATE", "UPDATE"],
    "entities": ["BOOKING"]
  }'

Управление webhooks

Получение списка

curl "https://backend.guestme.ru/api/v1/external/webhook" \
  -H "Authorization: Bearer TOKEN"

Обновление

curl -X PUT "https://backend.guestme.ru/api/v1/external/webhook/1" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/guestme",
    "events": ["CREATE", "UPDATE", "DELETE"],
    "entities": ["BOOKING", "RESTAURANT"]
  }'

Удаление

curl -X DELETE "https://backend.guestme.ru/api/v1/external/webhook/1" \
  -H "Authorization: Bearer TOKEN"

Типы событий

Каждый webhook можно подписать на определённые комбинации событий и сущностей:

Событие	Сущность	Когда срабатывает
CREATE	BOOKING	Создано новое бронирование
UPDATE	BOOKING	Статус бронирования изменился
DELETE	BOOKING	Бронирование удалено
CREATE	RESTAURANT	Ресторан подключён к системе
UPDATE	RESTAURANT	Данные ресторана обновлены
DELETE	RESTAURANT	Ресторан удалён из системы

Формат уведомления

GuestMe отправляет POST-запрос на URL webhook с JSON-телом WebhookEventExternalDto:

Поле	Тип	Описание
uuid	UUID	Уникальный идентификатор события
date	date-time	Дата и время события (ISO 8601)
event	enum	Тип события (CREATE, UPDATE, DELETE)
entity	enum	Тип сущности (BOOKING, RESTAURANT)
data	object	Данные — BookingExternalDto или RestaurantExternalDto

Пример тела уведомления:

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "date": "2025-06-15T19:05:00Z",
  "event": "CREATE",
  "entity": "BOOKING",
  "data": {
    "id": 5001,
    "status": "CREATED",
    "firstName": "Иван",
    "phone": "+79991234567",
    "date": "2025-06-15T19:00:00Z",
    "persons": 2
  }
}

Авторизация запросов

Для защиты вашего эндпоинта от несанкционированных запросов укажите token и authorizationHeaderPrefix при создании webhook.

GuestMe будет отправлять заголовок Authorization с вашим token. Если задан authorizationHeaderPrefix, токен передаётся с префиксом:

Authorization: {authorizationHeaderPrefix} {token}

Если authorizationHeaderPrefix не указан, передаётся только токен:

Authorization: {token}

Тестирование

Для локальной разработки используйте ngrok для создания публичного URL к вашему локальному серверу.