外部連携を点検する

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

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

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

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

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

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

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

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

一覧には Webhook 呼び出し日時 と Call 結果 だけが簡略に表示され、どの宛先に何のために送ったかといった残りの情報は、行を押して詳細を開くと表示されます。一覧が古く見える場合は、右上の Calls を更新 で再読み込みできます。

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

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

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

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

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

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

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

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

1. 新商品通知ボット の Webhook Calls タブで、結果が失敗の行を押してください。Webhook Call 詳細 画面が開きます。
2. リクエスト で、どの宛先に、どんな内容を送ったかを確認してください。
3. レスポンス で、応答コードと、外部のプログラムが返した内容を確認してください。

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

外部のプログラムの担当者にこの呼び出しをそのまま渡したい場合は、右上の cURL をコピー で、この呼び出しを再現できる形にコピーして送ることができます。

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

この Webhook が、応答を返して値を埋める WriteBack も併用している場合は、その各動作が成功したか失敗したかも、同じ詳細の WriteBack 結果 タブで見ることができます。項目ごとの意味は Webhook で扱います。

失敗したときの対応

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

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

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

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

次にすること

• Webhook: Webhook が何であり、新しく作ったり、オン・オフしたり、宛先・条件を修正したりする方法を扱います。
• Webhook: 応答を返して値を埋める WriteBack を使うとき、各動作がどうなったかを呼び出しの詳細で確認する方法を扱います。