Регистрация эндпоинта
В 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-время в секундах.
- Извлеките
tиsиз заголовка. - Объедините временную метку, точку и точные байты исходного тела запроса.
- Вычислите HMAC-SHA256, используя секретный ключ подписи эндпоинта.
- Сравните шестнадцатеричный результат с помощью сравнения с постоянным временем выполнения (constant-time).
Сохранение перед подтверждением
Сохраните валидированное событие в надежную очередь или транзакционный inbox перед возвратом2xx. Если хранилище недоступно, верните ошибку, чтобы доставку можно было повторить. После надежного сохранения передайте обработку бизнес-ошибок вашему воркеру с собственными повторными попытками.
Этот обработчик Express использует операцию persistEvent, предоставляемую приложением. Реализуйте ее как атомарную вставку с ключом по id события; уже сохраненное событие должно считаться успешным. Не помечайте событие как обработанное до фиксации его бизнес-транзакции.
Пример для Java и Spring
Этот пример на Java 17 применяет тот же порядок проверки и надежного сохранения. Предоставьте бинEventInbox, поддерживаемый транзакционным хранилищем с ограничением уникальности по ID события. Метод insertIfAbsent должен зафиксировать событие целиком перед возвратом; дублирующиеся ID возвращают успешный результат. Затем ваш воркер сможет обработать и пометить сохраненные события в рамках собственной транзакции.
Тайминги, повторные попытки и приостановка
Возвращайте ответ2xx незамедлительно; стремитесь к времени менее 6 секунд. Медленные ответы длительностью более 10 секунд могут снизить приоритет доставки. Не выполняйте длительные бизнес-операции внутри HTTP-обработчика.
Для ответа, отличного от 2xx, или при отсутствии ответа интервалы повторных попыток по умолчанию составляют:
YCloud прекращает повторные попытки для этого события после достижения настроенного лимита. При настройках по умолчанию URL может быть приостановлен на 3 минуты при достижении 200 сбоев в минуту или суммарного времени сбоев в 10 минут в течение одной минуты по параллельным запросам. Запросы приостанавливаются на это время и возобновляются после.
Также отслеживайте
status эндпоинта. Эндпоинт со статусом pending не получает события; см. раздел конфигурация эндпоинта.
Проверка вашего приемника
- Действительная подпись и надежно сохраненное событие возвращают
2xx. - Измененные тела запросов, некорректные подписи и устаревшие временные метки отклоняются.
- Повторяющееся событие принимается без повторного выполнения его бизнес-действия.
- Сбой хранилища возвращает ошибку и позволяет выполнить повторную доставку.
- Неизвестные типы событий не приводят к сбою в работе приемника.
- Ошибки обработки повторно отрабатываются вашим воркером после успешного принятия запроса.
- Секреты и полные полезные нагрузки клиентов не записываются в логи приложения.

