外部連携を点検する

洋服のオンラインショップ「ぬくもりクローゼット」では、新しい商品を登録すると、その事実を社内の通知ボットに自動で知らせる Webhook(コンテンツに変化が起きると外部のプログラムに通知を送る連携)を設定してあります。ところがある日、担当者が「最近、新商品の通知がまったく来ない」と言います。通知が本当に送られなかったのか、送られたのにボット側で見逃したのかを、まず切り分ける必要があります。

Webhook は一度作っておけば自動で動く仕組みなので、普段は気にかける必要がありません。しかし通知を受け取る外部のプログラムは、こちらの手が届かないところにあるため、いつか応答がなかったりエラーを返したりする日が来ます。このページでは、設定してある Webhook が正しく送られているかを確認し、失敗した呼び出しを見つけて原因に応じて対応する方法を、状況別のレシピとして扱います。

Webhook が何であり、どう作り、オン・オフし、修正するかは Webhook で扱います。ここでは、すでに作ってある Webhook を運用しながら点検する側に集中します。

呼び出し履歴に何が残るか

Webhook が外部のプログラムにリクエストを送るたびに、その一回一回が 呼び出し履歴 に記録として残ります。各記録には次の内容が含まれます。

• いつ送ったか、そして処理にかかった時間
• どんな変化をきっかけに送ったか(例: 商品の登録)
• どの宛先に送ったか
• 外部のプログラムが返した応答コード(リクエストをどう処理したかを知らせる結果番号)
• その呼び出しが成功だったか失敗だったか

呼び出し履歴は二つの層になっています。まず、呼び出しを時系列でたどる一覧があり、一覧から 1 件を開くと、その呼び出しの詳細が表示されます。詳細では、こちらが実際に送ったリクエストと、外部のプログラムが返したレスポンスを、そのまま見ることができます。

Webhook 一覧で名前を押すと詳細画面が開き、上部の 呼び出しログ タブにこの一覧が表示されます。「ぬくもりクローゼット」の 新商品通知ボット が商品を登録するたびに送った記録は、次のように表示されます。

一覧には一行ごとに 呼び出し時刻、Call 結果(応答コード)、どんな変化がこの呼び出しを起こしたのか(イベントアクション)、かかった時間(所要時間)、その呼び出しを指す リクエスト ID が表示されます。どの宛先に送り、何をやり取りしたかは、行を押して詳細を開くと表示されます。結果 の欄で、成功した呼び出しと失敗した呼び出しだけを分けて絞り込むこともできます。一覧が古く見える場合は、右上の ログを更新 で再読み込みできます。

記録は長く残りません。 成功した呼び出しの記録は1時間、失敗した呼び出しの記録は3日後に消えます。失敗した側を長く置くのは、後で原因を見に行くことになるのが失敗のほうだからです。そのため「昨日はうまく送られていた通知」はすでに一覧にないことがあり、これは通知が送られなかったという意味ではありません。送信の記録を長く保管しなければならないなら、受け取る側のプログラムに残してください。

成功と失敗は応答コードで分かれます。応答コードが正常な範囲(おおむね 200 番台や 300 番台)であれば成功、それ以外の番号であれば失敗として記録されます。外部のプログラムがまったく応答しなかった場合や、返した応答が大きすぎる場合も、その呼び出しは失敗として残ります。

通知が正しく送られているか確認する

担当者の言うとおりかを確認するには、まず、この Webhook がこれまで送った呼び出しのうち何パーセントが成功したかを見ます。Webhook 一覧に呼び出し成功率がそのまま表示されています。

1. 洋服店の Space の設定で Webhook 画面を開いてください。
2. 一覧で 新商品通知ボット の行の 成功した Calls(%) 列を確認してください。

たとえば「66.67%」のように表示されます。100% であれば、これまで送った呼び出しがすべて成功したということで、その場合、見逃したのはボットの側です。100% より低ければ、通知そのものが送られる途中で止まったことがあるという意味なので、次の節でその原因を探します。

これまで送った呼び出しが 1 件もない場合、通知が失敗したのではなく、そもそも送られていません。Webhook がオフになっている(Inactive)か、設定した条件に合う変化がその間になかったときにそうなります。この場合は Webhook で、オンになっているか、どんな変化に反応するよう設定してあるかを確認してください。

失敗した呼び出しの原因を探す

失敗が見えたら、その呼び出しを 1 件開いて、何が問題だったかを見ます。詳細には、こちらが送ったリクエストと、外部のプログラムが返したレスポンスが一緒に表示されます。

1. 新商品通知ボット の 呼び出しログ タブで、結果が失敗の行を押してください。その呼び出しの詳細が開きます。
2. リクエスト で、どの宛先に、どんな内容を送ったかを確認してください。
3. 上部の ステータス で応答コードを、レスポンス で外部のプログラムが返した内容を確認してください。リソース・アクション には、どんな変化がこの呼び出しを起こしたのかが一緒に表示されます。

応答コードと返された内容が原因を教えてくれます。応答コードが失敗の範囲であれば、外部のプログラムはリクエストを受け取ったものの、処理の途中で失敗したということで、この場合は返された内容に原因が書かれていることが多いです。応答がまったくなかったり、宛先が見つからなかったりした場合は、送り先の宛先が変わったか、プログラムが停止している可能性があります。

外部のプログラムの担当者にこの呼び出しをそのまま渡したい場合は、右上の cURL をコピー で、この呼び出しを再現できる形にコピーして送ることができます。記録全体をファイルで渡すには .json をダウンロード を使ってください。

送られたリクエストには、こちらが一緒に送ったヘッダーも含まれています。そのうち秘密値として指定したもの(例: 外部のプログラムに接続するときに使う鍵の値)は、画面ではアスタリスクで隠されて表示されます。元の値は露出しないので、安心して詳細を確認できます。

失敗したときの対応

まず知っておくべきことが一つあります。失敗した呼び出しは自動で再送されません。 一度失敗した通知はそのまま履歴に残るだけで、Webhook が自動で再送することはありません。そのため対応は二つに分かれます。今後の通知が正しく送られるように原因を直すこと、そして、すでに失敗してボットが見逃したその件を自分で手当てすることです。

詳細で見た内容に応じて、考えられる原因と対応は次のとおりです。

宛先を直したり Webhook を再びオンにしたりする方法は Webhook で扱います。

原因を直しても、その間に失敗した通知が自動でまた送られることはありません。失敗した呼び出しがそれぞれどの商品の登録だったかは、その呼び出しの詳細の送信内容で確認できるので、それらの商品については、ボットの担当者に直接知らせて、抜けた処理を補います。

次にすること

• Webhook: Webhook が何であり、新しく作ったり、オン・オフしたり、宛先・条件を修正したりする方法を扱います。
• Webhook（API リファレンス）: 呼び出しの状態や送信記録をプログラムから照会するときに使うエンドポイントを扱います。