CircleCI の Webhook を使ってみた

この記事は CircleCI Advent Calendar 2021 の22日目の記事です。

こんにちは。CircleCI カスタマーサクセスチームのChisatoです。
今回は Webhook について紹介します。
初めてのQiita投稿なので、温かい目で読んでいただければ幸いです。

Webhook でできること

Webhookを使うと、管理先のプラットフォームでCircleCIからの情報（イベント）を受け取れます。
こちらのブログ では、「API が "プル" なのに対して、Webhook は "プッシュ" である」と表現しています。 APIとは異なり、イベント発生時に CircleCI が連携先サービスに情報を送信するためです。

Webhookのユースケースは下記引用のとおりいろいろあります。

• カスタム ダッシュボードを作成して、ワークフローやジョブのイベントの可視化または分析を行う。
• インシデント管理ツール（例：Pagerduty）にデータを送信する。
• Airtable などのツールを使ってデータを取得・可視化する。
• Slack などのコミュニケーション アプリにイベントを送信する。
• ワークフローがキャンセルされた場合に Webhook を使ってアラートを送信し、API を使ってそのワークフローを再実行する。
• ワークフローやジョブが完了したら内部通知システムをトリガーし、アラートを送信する。
• 独自の自動化ブラグインやツールを作成する。

Airtable にジョブの完了を送信

Airtableとは、「チームのコラボレーションを加速させるローコードプラットフォーム」です。さまざまなアプリとの連携が簡単にできます。
ここでは、CircleCIのジョブが完了するとテーブルに記録されるように設定します。
こちらのドキュメンテーションページを参考にしました。

６つのステップ

１．Airtable のアカウント作成

２．Base の作成

３．テーブルのコラム部分の設定

テーブルのコラムのタイトル部分をダブルクリックして、フィールドタイプを"Single ilne text"にセットします。
各コラムのタイトルを "ID", "Job Name", "Status", "Happened At"とします。

４．Automations の設定

右上の "Automations" をクリックして、"Create a custom automation" を選択します。
TRIGGER のタイプを "When webhook received" として、生成されたURLをコピーします。

次に、ACTIONSのタイプを "Create record" とします。
Tableを選択し、各フィールドに、対応するコラムとwebhookのデータを選択します。
TestをRunして動作確認したら、画面上部のトグルを ON にします。

５．CircleCI の Webhook の設定

CircleCI のUIで、Webhook を送信したいプロジェクトのページに移動します。
"Project Settings" ページ左側の最下部にある "Webhooks" を選択します。
”Add Webhook” を選択し、Webhook名と、先ほどコピーした Airtable のURLを入力します。
イベントのうち、"Job Completed"を選択して、"Add Webhook" をクリックします。

６．ジョブ完了後の動作確認

ジョブを走らせてみると、テーブルに記録されていることが確認できました。

ほほう。なかなかいいじゃない。
その後Slackに通知するなどして遊んでみましたが、簡単で楽しかったです。

ngrok との連携

ngrok..。 んぐ.. 。えぬじー..？
公式ドキュメントで確認すると、en-grok と発音することがわかりました。
ngrok は、トンネリングを用いて、ローカルサーバーをセキュアにインターネットに公開できるサービスです。

５つのステップ

１．ngrokのセットアップ

こちらを参考にngrokを設定しました。
セットアップの ngrok http 80 の部分でいきなり躓いたのですが、ngrok.yml に web_addr: localhost:8080 と追記することで通信できました。
また、いきなりブログ記事のプロジェクトに挑むのではなく、自分の既存のプロジェクトから Webhook を ngrok に 連携できることを確認してからブログ記事に進みました。

２．Personal API Token の生成

いよいよ、ブログ記事のプロジェクトに進みます。
サンプルプロジェクトのNode.jsサーバーが localhost:8080 を向いていたため、変更しました。
今回はステップ４で Signature のバリデーションを行いたいので、Personal API Token を生成しました。

３．Webhook の設定

Airtable のステップ５と同じ要領で Webhook を作成します。
今回はngrok で作成されたURLを追加し、先ほど生成した API Token を追加します。
（ngrok は無料プランだと新しい通信のたびにURLが更新されるようです。URLが更新されたときは、Webhook の Receiver URL を合わせて更新します。）

４．Signature のバリデーション設定

単純に Webhook を設定すると、「ウェブ上のどこからでも、エンドポイントのアドレスを知る相手からはイベントを受信できる」状態になっています。
Personal API Token を用いた設定を追加することで、「CircleCI Webhookからの情報しか受信しないように設定」できます。
詳細はこちらのブログ記事を参照ください。

Signature のバリデーション設定で躓いたので、CircleCI の Solutions Engineer の Tadashiさんに助けていただきました。
こちらの "const key" の部分を自分の token 名に変更します。

５．動作確認

Tadashiさんがいい感じにやってくださったおかげで、無事にこちらのプロジェクトについてもイベントを受信することができました。

まとめ

今回 Webhook を使ってみて、その設定方法の簡単さと、できることの多さに感動しました。特に、 Airtable との連携からSlackに通知するまでの流れがスムーズで心地よかったです。

このブログ記事をチェックしてくださったエンジニアの方から、「通常のGithubのコミットであれば、誰がいつワークフロー実行しているとかわかるのでいいなーと思いました。
https://circleci.com/docs/2.0/webhooks/#vcs」とコメントいただきました。
なるほど、まだまだ奥が深そうなWebhook。お客様にたくさん活用いただけるよう、勉強をがんばります。

ブログを書いた感想

こちらのアドベントカレンダーには、軽い気持ちで参加しました。
参加して間もなく、他の方々の素晴らしい記事を拝読して、自分がとても軽い気持ちで参加してしまったことに気づきました。
「何てことしてくれたんだよ、自分。そもそも書けることあるの？」と自分を責めました。
しかし、そのあとすぐに、自分が CircleCI を大好きな理由の１つを思い出しました。
それは、”社員の皆さんがとても優しく協力的なところ” です。
「調べてもわからなかったら、質問しよう。。」

そして、前述の Signature に関して Tadashi さん（Solutions Engineer）とJasur さん（DevOps Customer Engineer）に質問しながら、記事を書き終えることができました。しかも、お二人とも質問への回答のみならず、実際の動作が確認できるまで付き合ってくださいました。ありがとうございます。

2021年は、いつもお世話になっている方々への感謝の気持ちで締めたいと思います。
いつも優しくご指導いただき、ほんとうにありがとうございます。
日に日に寒くなってきている年末ですが、皆さんのおかげで、私の心の中はぽかぽかと温かいです。
2022年は、「我以外皆我師」の言葉を胸に精進したいと思います。

最後までお読みいただきありがとうございました。
どうぞ良いお年をお迎えください。

参考

Webhookの概要（CircleCI ドキュメンテーション）
Creating integrations, dashboards, notifications, and more using CircleCI webhooks（CircleCI Blog）
CircleCI webhooks with Airtable（CircleCI ドキュメンテーション）
Airtable
ngrok Documentaion