Перейти к основному содержанию

​
Настройка webhooks

Для начала работы с webhooks необходимо создать подписку на события через API.

​
Создание подписки

Для создания подписки на webhook используйте endpoint POST /v2/webhooks: 
curl -X POST https://b2b.every.ru/api/v2/webhooks \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://partner.example.com/webhooks",
    "events": ["booking.status.changed", "pass.status.changed"],
    "secret": "your-secret-key-here"
  }'
Параметры запроса:
  • url (обязательно): URL endpoint для приёма webhook-уведомлений. Должен быть доступен по HTTPS и возвращать статус 200 при получении уведомления.
  • events (обязательно): Массив типов событий, на которые необходимо подписаться. Минимум одно событие.
  • secret (опционально): Секретный ключ для подписи webhook-уведомлений. Рекомендуется использовать для проверки подлинности уведомлений. Длина от 16 до 256 символов.
Пример успешного ответа: 
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://partner.example.com/webhooks",
  "events": ["booking.status.changed", "pass.status.changed"],
  "active": true,
  "created_at": "2025-11-08T06:00:00Z",
  "updated_at": "2025-11-08T06:00:00Z"
}

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

Для получения списка всех ваших подписок используйте endpoint GET /v2/webhooks: 
curl -X GET https://b2b.every.ru/api/v2/webhooks \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <TOKEN>'
Пример ответа: 
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "url": "https://partner.example.com/webhooks",
      "events": ["booking.status.changed", "pass.status.changed"],
      "active": true,
      "created_at": "2025-11-08T06:00:00Z",
      "updated_at": "2025-11-08T06:00:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1
  }
}

​
Получение информации о подписке

Для получения информации о конкретной подписке используйте endpoint GET /v2/webhooks/{webhookID}: 
curl -X GET https://b2b.every.ru/api/v2/webhooks/123e4567-e89b-12d3-a456-426614174000 \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <TOKEN>'

​
Обновление подписки

Для обновления подписки (изменение URL, списка событий или секретного ключа) используйте endpoint PATCH /v2/webhooks/{webhookID}: 
curl -X PATCH https://b2b.every.ru/api/v2/webhooks/123e4567-e89b-12d3-a456-426614174000 \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://partner.example.com/webhooks/new",
    "events": ["booking.status.changed", "pass.status.changed"],
    "active": true
  }'
Параметры запроса (все опциональны):
  • url: Новый URL endpoint для приёма webhook-уведомлений
  • events: Новый список событий для подписки
  • secret: Новый секретный ключ для подписи уведомлений
  • active: Флаг активности подписки. Если false, уведомления не будут отправляться, но подписка сохранится

​
Удаление подписки

Для удаления подписки используйте endpoint DELETE /v2/webhooks/{webhookID}: 
curl -X DELETE https://b2b.every.ru/api/v2/webhooks/123e4567-e89b-12d3-a456-426614174000 \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --header 'Authorization: Bearer <TOKEN>'
После удаления подписки уведомления больше не будут отправляться.

​
Формат webhook-уведомлений

Все webhook-уведомления отправляются в формате JSON и содержат следующую структуру: 
{
  "event": "booking.status.changed",
  "timestamp": "2025-11-08T06:00:00Z",
  "data": {
    // Данные события (зависят от типа события)
  }
}

​
Поля уведомления

  • event (обязательно): Тип события. Используйте это поле для определения, как обрабатывать уведомление. Доступные события:
    • booking.status.changed — изменение статуса бронирования
    • pass.status.changed — изменение статуса прохода
  • timestamp (обязательно): Время возникновения события в формате ISO 8601 (UTC).
  • data (обязательно): Данные события. Структура зависит от типа события.

​
Безопасность

​
Проверка подлинности уведомлений

Для обеспечения безопасности рекомендуется использовать секретный ключ для подписи webhook-уведомлений. При указании secret при создании или обновлении подписки, все уведомления будут подписаны с использованием HMAC-SHA256. Заголовок подписи: Подпись передаётся в заголовке X-Webhook-Signature: 
X-Webhook-Signature: sha256=abc123def456...
Проверка подписи: Для проверки подлинности уведомления:
  1. Получите значение заголовка X-Webhook-Signature
  2. Извлеките подпись (часть после sha256=)
  3. Вычислите HMAC-SHA256 от тела запроса (raw body) с использованием вашего секретного ключа
  4. Сравните вычисленную подпись с полученной подписью
Важно:
  • Всегда проверяйте подпись перед обработкой уведомления
  • Используйте безопасное сравнение подписей (constant-time comparison) для предотвращения timing attacks
  • Храните секретный ключ в безопасном месте (не в коде)

​
Требования к endpoint

Ваш webhook endpoint должен:
  • Быть доступен по HTTPS: Webhook-уведомления отправляются только на HTTPS endpoints
  • Возвращать статус 200: При успешном получении уведомления endpoint должен возвращать HTTP статус 200
  • Обрабатывать запросы быстро: Рекомендуется обрабатывать уведомления асинхронно, чтобы не блокировать ответ
  • Быть идемпотентным: Одно и то же уведомление может быть отправлено несколько раз, ваша система должна корректно обрабатывать повторные уведомления

​
Обработка ошибок

​
Ответы вашего endpoint

Ваш webhook endpoint должен возвращать следующие HTTP статусы:
  • 200 OK: Уведомление успешно получено и обработано
  • 400 Bad Request: Некорректный формат уведомления (не рекомендуется возвращать, лучше логировать)
  • 500 Internal Server Error: Внутренняя ошибка обработки (API может повторить отправку)

​
Повторные попытки

Если ваш endpoint возвращает ошибку (не 200) или не отвечает в течение таймаута, API может повторить отправку уведомления. Повторные попытки выполняются с экспоненциальной задержкой. Рекомендации:
  • Всегда возвращайте 200 OK после успешной обработки уведомления
  • Обрабатывайте ошибки внутри вашего endpoint и возвращайте 200 OK, даже если обработка не удалась (логируйте ошибки для последующего анализа)
  • Используйте очереди сообщений для асинхронной обработки уведомлений

​
Авторизация

Для работы с webhooks требуется scope webhooks в вашем Bearer токене. Убедитесь, что при получении токена вы указали этот scope: 
curl -X POST https://auth.every.ru/oauth/v2/token \
  -u "client_id:client_secret" \
  -d "grant_type=client_credentials" \
  -d "scope=webhooks booking.lounges booking.fast_tracks"
Подробнее об авторизации см. документацию по авторизации.

​
Ограничения

  • Максимальный размер тела webhook-уведомления: 64 KB
  • Таймаут ожидания ответа от вашего endpoint: 30 секунд
  • Максимальное количество подписок на один партнёра: 100

​
Поддержка

При возникновении проблем с webhooks:
  1. Проверьте логи вашего webhook endpoint
  2. Убедитесь, что endpoint доступен по HTTPS и возвращает статус 200
  3. Проверьте подпись уведомлений (если используется)
  4. Обратитесь в поддержку с request_id из ответов API