Webhookとは？変更を知らせる仕組みと、通知だけでは終わらない連携

予約や申請が登録されたら、別のシステムにも知らせたい。こうした連携に使われるのがWebhookです。受け取り側から何度も確認する方法との違いと、通知の重複・取りこぼしを考える理由を説明します。

出来事が起きた側から、通知を送る

Webhookは、ある出来事が起きたとき、登録された送信先へデータを送る仕組みです。「イベント」は、その通知のきっかけとなる登録・更新などを指します。

GitHubのWebhook解説では、イベントを購読し、発生時に指定したURLへHTTPリクエストを送る方法を説明しています。必要な情報があるかを繰り返し問い合わせるポーリングと異なり、変更が起きた側から知らせる流れです。

APIとWebhookは、常にどちらか一つを選ぶ関係ではありません。Webhookで変更を知り、必要な詳細をAPIで取りに行く構成も考えられます。必要なときに一度読む用途と、変化を受け取る用途を分けると整理しやすくなります。

架空の予約サービスが、予約の作成を社内の予定表へ通知する場面を考えてみましょう。予約の登録、通知の送信、通知の受け取り、予定表への反映は、それぞれ別の段階です。

通知を受け取ったことだけでは、予定表への登録まで完了したとは限りません。 受け取り側が後で処理する構成なら、受付後に登録が失敗する場合も考えられます。

本記事では、通知のIDと処理結果を対応付けて、どの段階まで進んだかを追えるようにする考え方を提案します。利用者の画面で単に「連携済み」と示すなら、その言葉がどの状態を意味するのかも決める必要があります。

連携先の停止や通信失敗に備え、通知を送り直す仕組みが使われることがあります。再送の条件や、自動か手動かはサービスによって異なるので、仕様で確認しなければなりません。

GitHubのWebhookの推奨事項は、配信を識別するIDの利用と、再配信でも元と同じIDが使われることを説明しています。この仕様を、すべてのWebhook提供者に共通する保証として扱うことはできません。

予約の仮例なら、同じ出来事を受け取った際に予定をもう一つ作らず、前に処理した結果を確かめる方法が考えられます。こうした、繰り返しても意図しない重複を生まない性質を「冪等性」と呼びます。どのIDで同じ処理と判断するかを、対象の仕様に合わせて決めることが要点です。

通知の受け取り口には外からデータが届きます。送信元を名乗る項目があるだけでは、それを信用してよいとは限りません。GitHubの同資料では、秘密値を用いた検証とHTTPSの利用などを案内しています。

実装する際は、その提供者が定める検証方法を使う必要があります。連携用の秘密値を公開URLや共有メモに書くのは避け、運用担当者が管理する仕組みで扱います。

確認時には、正常な一件に加え、同じ通知の再送、受け取り側が止まっていた場合、不正な通知を想定すると、運用上の穴を見つける材料になります。順番や配信保証、記録の保存期間も確認項目です。通知が来ることだけを頼りにせず、必要に応じて処理結果を照合・復旧できる方法を用意するとよいでしょう。

連携の入口を整理するにはAPI連携の基本、端末への保存と共有完了の違いにはオフライン対応の考え方も参考になります。