Вебхуки Orbit

Webhooks отправляют подписанный HTTP POST на выбранный вами URL каждый раз, когда состояние развёртывания меняется, так что ваша команда узнает о неудачной сборке в канале, который они уже смотрят, вместо того чтобы узнать об этом от клиента.

Где находятся Webhooks

Откройте Orbit, нажмите на проект и выберите Webhooks в группе Configure на панели вкладок проекта. Страница называется Webhooks и описана как получение HTTP POST уведомлений при изменении состояния развёртываний с поддержкой Slack, Discord и универсального JSON.

Добавление Webhook

1. На карточке Add a webhook введите Label. Например, название места, куда он отправляет данные.
2. Вставьте URL. Он должен начинаться с https://.
3. В разделе Trigger on отметьте события, которые вам нужны.
4. Нажмите Add webhook.

Секрет подписи показывается один раз сразу после создания с предупреждением, что он больше не будет отображаться. Скопируйте его перед тем как перейти дальше.

Проект может содержать до десяти webhooks. Попытка добавить одиннадцатый будет отклонена с сообщением об этом ограничении.

Пять событий

Выбирайте осознанно. Подписка на все пять событий в активном проекте превратит полезный канал оповещений в шум, который все отключат. Для большинства команд Failed в одиночку это правильная отправная точка, с добавлением Succeeded только там, где уведомление о развёртывании действительно полезно, например в канале продакшена.

Slack и Discord

Если URL это входящий webhook Slack или webhook Discord, Orbit определяет это по URL и отправляет форматированное сообщение вместо сырого JSON. Страница указывает на это под полем URL: Slack и Discord URL определяются автоматически.

Форматированное сообщение содержит имя проекта, событие, ветку, короткий коммит, время сборки, развёрнутый URL и текст ошибки при сбое. Цвет зависит от события, поэтому красная карточка в канале означает сбой без необходимости кого-либо её читать.

Больше ничего не требуется. Создайте входящий webhook в Slack или Discord, вставьте URL сюда, выберите ваши события и вы готовы.

Универсальные JSON payload

Любой другой URL получает тело JSON. Поля:

Используйте deliveryId чтобы сделать ваш endpoint идемпотентным. Если вы повторяете доставку или сетевой сбой вызывает дубликат, id позволяет вам узнать, что вы уже обработали его.

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

Каждая доставка содержит три заголовка:

• X-Orbit-Signature-256, HMAC-SHA256 точного тела запроса, используя ваш секрет подписи, отформатированный как sha256= за которым следует шестнадцатеричный дайджест.
• X-Orbit-Event, имя события.
• X-Orbit-Delivery, id доставки.

Проверьте подпись перед тем как действовать на основе payload. Вычислите тот же HMAC для сырых байтов тела и сравните, используя сравнение с постоянным временем вместо сравнения строк.

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.ORBIT_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  return res.status(401).end();
}

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

Каждая строка webhook имеет Send test delivery. Она отправляет реальную доставку на ваш endpoint немедленно и сообщает полученный HTTP код или деталь сбоя.

Используйте это сразу после добавления webhook, прежде чем на него полагаться. Правило брандмауэра или маршрут, который принимает только GET, намного легче найти сейчас, чем во время инцидента.

История доставок

Каждая строка содержит спарклайн последних семи дней с количеством доставок, процентом успеха и средней продолжительностью, плюс время последней отправки и её результат.

Разверните Show delivery history для отдельных доставок: событие, код ответа, продолжительность и текст ошибки где она была. Любая доставка может быть повторно отправлена с помощью Retry delivery, который сообщает полученный код.

Доставки истекают через двенадцать секунд. Если ваш endpoint выполняет медленную работу, сначала подтвердите с 200, а затем обрабатывайте позже, вместо того чтобы держать соединение открытым.

Ротация секрета

Нажмите Rotate secret. Новый секрет отображается один раз, и всплывающая подсказка явно указывает, что старый секрет становится недействительным немедленно.

Это означает короткое окно, в течение которого доставки подписываются секретом, который ваш endpoint не знает. Планируйте это: ротируйте в спокойный момент и обновите ваш endpoint как очень следующее действие.

Ротируйте когда кто-то с доступом к секрету уходит, или если он когда-либо был вставлен в общий канал или тикет.

Отключение и удаление

Disable webhook останавливает доставки, но сохраняет конфигурацию и историю, и строка показывает значок Disabled. Это правильный выбор когда вы приостанавливаете оповещения, например во время запланированной миграции, которая произведёт много шума.

Delete webhook удаляет его полностью. Используйте отключение, если вы не уверены.

Другие способы получить уведомления

Webhooks это гибкий вариант. Два более лёгких альтернативных варианта находятся в Settings:

• Deploy email notifications с тремя настройками: все развёртывания, только сбои или отключено.
• Notification channels, которые отправляют на webhook URL при успехе или сбое развёртывания, регрессии сборок и регрессии пакетов, со своей собственной историей доставок и кнопкой тестирования.

См. Параметры проекта Orbit для обоих.

Решение проблем

Доставки показывают ошибку с HTTP кодом. Ваш endpoint вернул ошибку. Код говорит какую: 404 означает что путь неправильный, 401 или 403 обычно означает что ваша собственная проверка подписи его отклоняет, и 500 означает что ваш обработчик выбросил исключение.

Доставки не выполняются с истечением времени ожидания. Ваш endpoint работал дольше двенадцати секунд. Верните 200 немедленно и выполняйте работу асинхронно.

Ничего вообще не доставляется. Проверьте что webhook включён и что событие которое вы ожидали отмечено. Сборка которая никогда не встала в очередь не срабатывает на событие queued.

Подпись никогда не проверяется. Почти всегда проблема со сырым телом описанная выше. Логируйте точные байты которые вы хешируете и сравните их длину с заголовком Content-Length.

Slack URL отправляется как сырой JSON. Входящие webhooks Slack находятся под hooks.slack.com. Другой Slack URL не будет определён как таковой.

Что дальше

• Запуск развёртываний через Deploy Hooks для входящего направления.
• Параметры проекта Orbit для email уведомлений и каналов уведомлений.
• Страница статуса Orbit чтобы сообщить вашим клиентам, а не только вашей команде.