Orbit Webhooks

Webhooksは、デプロイメントが状態を変更するたびに署名されたHTTP POSTを選択したURLにプッシュするため、チームは顧客から聞き出す代わりに、すでに見守っているチャネルで失敗したビルドについて知ることができます。

Webhooksの場所

Orbitを開き、プロジェクトをクリックして、プロジェクトタブストリップのConfigureグループの下のWebhooksを選択します。ページのタイトルはWebhooksで、デプロイメントが状態を変更するときにHTTP POST通知を受け取ることを説明しており、Slack、Discordおよび汎用JSONがサポートされています。

Webhookの追加

1. Add a webhookカードで、Labelを指定します。投稿先の宛先のようなもの。
2. URLを貼り付けます。https://で始まる必要があります。
3. Trigger onの下で、必要なイベントをチェックします。
4. Add webhookをクリックします。

署名シークレットは作成直後に1回だけ表示され、再度表示されないという警告があります。ナビゲートして移動する前にコピーしてください。

プロジェクトは最大10個のwebhooksを保持できます。11番目を追加しようとするとリミットを示すメッセージで拒否されます。

5つのイベント

意図的に選択してください。ビジーなプロジェクトで5つすべてに購読すると、便利なアラートチャネルがみんながミュートするノイズに変わります。ほとんどのチームでは、Failedのみが正しい開始点であり、Succeededは本番チャネルなどデプロイ通知が本当に有用な場合にのみ追加されるべきです。

SlackおよびDiscord

URLがSlack着信webhookまたはDiscord webhookである場合、OrbitはURLから検出し、生JSONではなくフォーマット済みのメッセージを送信します。ページはURLフィールドの下でそう述べています: SlackおよびDiscord URLは自動検出されます。

フォーマット済みメッセージには、プロジェクト名、イベント、ブランチ、短いコミット、ビルド時間、デプロイされたURL、および何か失敗したときのエラーテキストが含まれます。色はイベントに従うため、チャネル内の赤いカードは誰もが読まずに失敗を意味します。

他には何も必要ありません。SlackまたはDiscordで着信webhookを作成し、ここにURLを貼り付けて、イベントを選択すれば完了です。

汎用JSONペイロード

他のURLはJSONボディを受け取ります。フィールドは次のとおりです:

deliveryIdを使用してエンドポイントをべき等にしてください。配信を再試行した場合、またはネットワーク障害が重複を引き起こした場合、IDはすでに処理したことを認識するのに役立ちます。

署名の検証

すべての配信は3つのヘッダーを含みます:

• X-Orbit-Signature-256、署名シークレットを使用した正確なリクエストボディのHMAC-SHA256で、sha256=の後に16進数ダイジェストが続く形式。
• X-Orbit-Event、イベント名。
• X-Orbit-Delivery、配信ID。

ペイロードに対して動作する前に署名を検証してください。生のボディバイトで同じ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があります。すぐにエンドポイントへの実際の配信をトリガーして、取得したHTTPコードまたは失敗の詳細を報告します。

webhookを追加した直後に使用してから、これに依存してください。ファイアウォールルールまたはGETのみを受け入れるルートは、インシデント中よりもここで見つけるほうがはるかに簡単です。

配信履歴

各行は、配信数、成功率および平均期間を示す過去7日間のスパークバー、および最後に発火した時刻とその結果を示します。

Show delivery historyを展開して個々の配信を表示します: イベント、応答コード、期間、および失敗があった場合のエラーテキスト。Retry deliveryで任意の配信を再送信でき、取得したコードを報告します。

配信は12秒後にタイムアウトします。エンドポイントが遅い作業を行う場合は、接続を開いたままにするのではなく、まず200で確認して後で処理してください。

シークレットのローテーション

Rotate secretをクリックします。新しいシークレットが1回表示され、ツールチップは古いシークレットが直ちに無効になることを明示しています。

つまり、配信がエンドポイントが知らないシークレットで署名される短いウィンドウがあります。計画してください: 静かな瞬間にローテーションし、エンドポイントを次のアクションとして更新してください。

シークレットへのアクセス権を持つ誰かが去ったとき、またはそれが共有チャネルやチケットに貼り付けられたことがある場合にローテーションしてください。

無効化と削除

Disable webhookは配信を停止しますが、構成および履歴を保持し、行はDisabledバッジを表示します。計画された移行時など、アラートを一時停止している場合は、これが正しい選択です。

Delete webhookはそれを完全に削除します。確実でない限り無効化を使用してください。

その他の通知方法

Webhooksは柔軟なオプションです。2つの軽いオプションはSettingsにあります:

• Deploy email notifications、3つの設定: すべてのデプロイ、失敗のみ、またはオフ。
• Notification channels、デプロイの成功または失敗、ビルドの回帰、バンドル回帰に対するwebhook URLにポストし、独自の配信履歴とテストボタンを備えています。

詳細はOrbitプロジェクト設定を参照してください。

トラブルシューティング

配信がHTTPコードで失敗したもの。 エンドポイントがエラーを返しました。コードはそれがどれであるかを告げます: 404はパスが間違っていることを意味し、401または403は通常、独自の署名チェックがそれを拒否していることを意味し、500はハンドラーがスローしたことを意味します。

配信がタイムアウトで失敗。 エンドポイントは12秒以上かかりました。直ちに200を返して、非同期で作業を行ってください。

まったく配信されない。 webhookが有効化されていることと、想定したイベントがチェックされていることを確認してください。キューに入らないビルドはキューイベントを発火しません。

署名が検証されない。 ほぼ常に上記で説明した生ボディ問題です。ハッシング中のバイト全体をログに記録し、Content-Lengthヘッダーの長さと比較してください。

Slack URLが生JSONで送信されている。 Slack着信webhooksはhooks.slack.comの下にあります。別のSlack URLは1つとして検出されません。

次にどこへ

• デプロイフックによるデプロイメントのトリガー: 着信方向の場合。
• Orbitプロジェクト設定: メール通知および通知チャネル用。
• Orbitステータスページ: チームだけでなく顧客に知らせてください。