Webhooks в Cloud
Cloud webhooks отправляют события жизненного цикла инстанса Пространства на публичный HTTP(S)-адрес; для продакшена используйте HTTPS. Настройка находится в Кабинет Cloud → Webhooks. Владелец, администратор или редактор Пространства может создать, проверить, сменить секрет и деактивировать webhook.
Создание и проверка webhook
- Укажите понятное название и публичный HTTP(S) URL.
- Выберите одно или несколько событий.
- Создайте webhook и сразу скопируйте секрет подписи. Открытый секрет показывается только один раз.
- Нажмите Отправить тест, чтобы проверить доступность endpoint и подпись. Тест отправляется только выбранному webhook.
Пока создание или смена возвращает одноразовый секрет, кабинет удерживает страницу Webhooks и выбранное Пространство. После показа секрета уход или переключение Пространства требует подтверждения; обновление списка webhook не скрывает секрет. Если при создании секрет не пришёл, не меняйте форму и снова нажмите «Создать». Если браузерное хранилище вкладки доступно, кабинет хранит точный ожидающий запрос в ней до 24 часов, восстанавливает его после перезагрузки только для той же учётной записи и Пространства и никогда не отправляет автоматически. Не начинайте создание другого webhook, пока не восстановили результат или явно не отбросили ожидающий повтор.
Для автоматизации передавайте стабильный Idempotency-Key при POST /api/v1/cloud/webhooks?workspace_id={workspace_id}. Если ответ потерян, повторите тот же запрос с тем же ключом в течение 24 часов: вернутся прежние ID webhook и секрет подписи. Изменённый запрос с тем же ключом даст 409 idempotency_conflict. Кабинет создаёт этот ключ и повторно использует его после неоднозначной ошибки автоматически.
В CLI команды mockarty-cli cloud-webhooks create и rotate-secret принимают --request-id. Если CLI создал ключ сам и запрос завершился ошибкой, ключ будет указан в тексте ошибки. Только при неизвестном результате повторите ту же команду с --request-id <указанный-ключ>. Храните ключ приватно вместе с учётными данными: авторизованный клиент может получить с ним одноразовый секрет повторно.
Поддерживаются события:
space.deleted— пространство удалено. Удаление какое-то время ещё можно отменить, поэтому считайте это предупреждением, а не окончательным состоянием;webhook.test— отправляется только кнопкой Отправить тест, выбранному webhook.
Событие * подписывает webhook на все поддерживаемые события, включая те, что
появятся позже. Пустой выбор равнозначен *.
Событие вне этого списка отклоняется при создании webhook, поэтому подписаться
на то, что никогда не придёт, нельзя. Прочитать актуальный список из своего кода:
curl -H "Authorization: Bearer $MOCKARTY_CLOUD_TOKEN" \
https://cloud.mockarty.ru/api/v1/cloud/webhooks/events
Проверка запросов
Каждый запрос содержит:
X-Mockarty-Event— название события;X-Mockarty-Delivery-ID— стабильный ID доставки для дедупликации повторов;X-Mockarty-Timestamp— Unix timestamp, участвующий в подписи;X-Mockarty-Signature— HMAC-SHA256 в форматеt=<timestamp>,v1=<hex digest>.
Вычислите HMAC-SHA256 от <timestamp>.<неизменённое тело запроса> с секретом подписи, сравните значение за постоянное время и отклоняйте устаревшие timestamp согласно вашей политике безопасности. Проверяйте неизменённое тело до разбора JSON.
Доставка работает как минимум один раз: timeout или временная ошибка получателя могут привести к повтору. После успешной обработки сохраните X-Mockarty-Delivery-ID, чтобы повтор не применил одно бизнес-действие дважды.
Смена секрета подписи
Используйте Сменить секрет, если секрет мог быть раскрыт или перенесённый webhook требует ротации. Сразу скопируйте новое значение и обновите получателя до следующего теста.
Для автоматизации доступен запрос:
POST /api/v1/cloud/webhooks/{webhook_id}/rotate-secret?workspace_id={workspace_id}
Idempotency-Key: <стабильный ключ этой конкретной ротации>
Ответ один раз содержит новый secret. Неоднозначный запрос повторяйте с тем же Idempotency-Key: для того же webhook и запроса Mockarty вернёт тот же credential. Повторное использование ключа с другим запросом вернёт 409 idempotency_conflict.
Если кабинет сообщает об успешной смене без секрета, снова нажмите Сменить секрет у этого webhook: повтор использует тот же ключ. Если хранилище вкладки доступно, точный повтор переживает перезагрузку в той же вкладке до 24 часов. Кабинет никогда не повторяет запрос автоматически и спрашивает подтверждение перед отказом от ожидающей смены ради другого webhook или Пространства.
Создание и ротация webhook возвращают credentials, поэтому эти операции намеренно не публикуются как AI/MCP tools.
История доставок и деактивация
Откройте Доставки, чтобы посмотреть статус и время попытки. Webhook деактивируется без удаления истории доставок. Неактивный webhook не получает новые события, а существующая история остаётся доступна авторизованным участникам воркспейса.
Если после смены конфигурации ключей секрет подписи не расшифровывается, восстановите исходный Cloud PII encryption key или смените секрет webhook. Не копируйте секреты подписи в логи, задачи и чаты.