Skip to main content
Принимайте события YCloud на общедоступном эндпоинте и обрабатывайте их без потери или повторного выполнения бизнес-действий. Используйте HTTPS для продакшена, сохраняйте исходное тело запроса и проверяйте каждую подпись перед приемом события.

Регистрация эндпоинта

В YCloud Console перейдите в раздел Developers > Webhook, выберите Add Endpoints, укажите Endpoints URL, выберите Events и сохраните с помощью Confirm. Вы также можете использовать POST /v2/webhookEndpoints; формат запроса и ответа см. в разделе Настройка Webhook.
  • Вы можете настроить до 20 эндпоинтов на одну учетную запись.
  • URL должен быть общедоступным и не должен разрешаться в приватный IP-адрес.
  • URL поддерживает до 500 символов; необязательное описание поддерживает до 400 символов.
  • Надежно сохраните возвращенный секрет подписи secret.

Чтение запроса события

Полные примеры см. в разделе Полезная нагрузка Webhook.

Проверка подписи

Заголовок YCloud-Signature имеет формат t=TIMESTAMP,s=SIGNATURE. Временная метка представляет собой Unix-время в секундах.
  1. Извлеките t и s из заголовка.
  2. Объедините временную метку, точку и точные байты исходного тела запроса.
  3. Вычислите HMAC-SHA256, используя секретный ключ подписи эндпоинта.
  4. Сравните шестнадцатеричный результат с помощью сравнения с постоянным временем выполнения (constant-time).
Не сериализуйте распарсенный JSON для повторной сборки тела. Пробелы, порядок ключей или экранирование Unicode меняют входные данные для подписи. В приведенном ниже примере также используется настраиваемый пятиминутный допуск по времени для снижения риска атак повторного воспроизведения. Этот допуск является политикой приложения, а не крайним сроком повторных попыток YCloud. Следите за синхронизацией часов вашего сервера.

Сохранение перед подтверждением

Сохраните валидированное событие в надежную очередь или транзакционный inbox перед возвратом 2xx. Если хранилище недоступно, верните ошибку, чтобы доставку можно было повторить. После надежного сохранения передайте обработку бизнес-ошибок вашему воркеру с собственными повторными попытками. Этот обработчик Express использует операцию persistEvent, предоставляемую приложением. Реализуйте ее как атомарную вставку с ключом по id события; уже сохраненное событие должно считаться успешным. Не помечайте событие как обработанное до фиксации его бизнес-транзакции.

Пример для Java и Spring

Этот пример на Java 17 применяет тот же порядок проверки и надежного сохранения. Предоставьте бин EventInbox, поддерживаемый транзакционным хранилищем с ограничением уникальности по ID события. Метод insertIfAbsent должен зафиксировать событие целиком перед возвратом; дублирующиеся ID возвращают успешный результат. Затем ваш воркер сможет обработать и пометить сохраненные события в рамках собственной транзакции.
Не используйте отдельную запись «already processed» в Redis перед постановкой события в очередь: если постановка в очередь завершится сбоем после этой записи, повторная попытка может быть отброшена. Используйте атомарный, надежный inbox или очередь, где прием и обработка дубликатов выполняются атомарно.

Тайминги, повторные попытки и приостановка

Возвращайте ответ 2xx незамедлительно; стремитесь к времени менее 6 секунд. Медленные ответы длительностью более 10 секунд могут снизить приоритет доставки. Не выполняйте длительные бизнес-операции внутри HTTP-обработчика. Для ответа, отличного от 2xx, или при отсутствии ответа интервалы повторных попыток по умолчанию составляют: YCloud прекращает повторные попытки для этого события после достижения настроенного лимита. При настройках по умолчанию URL может быть приостановлен на 3 минуты при достижении 200 сбоев в минуту или суммарного времени сбоев в 10 минут в течение одной минуты по параллельным запросам. Запросы приостанавливаются на это время и возобновляются после. Также отслеживайте status эндпоинта. Эндпоинт со статусом pending не получает события; см. раздел конфигурация эндпоинта.

Проверка вашего приемника

  • Действительная подпись и надежно сохраненное событие возвращают 2xx.
  • Измененные тела запросов, некорректные подписи и устаревшие временные метки отклоняются.
  • Повторяющееся событие принимается без повторного выполнения его бизнес-действия.
  • Сбой хранилища возвращает ошибку и позволяет выполнить повторную доставку.
  • Неизвестные типы событий не приводят к сбою в работе приемника.
  • Ошибки обработки повторно отрабатываются вашим воркером после успешного принятия запроса.
  • Секреты и полные полезные нагрузки клиентов не записываются в логи приложения.