WhatsApp Webhook エンドポイントの認証

Meta は具体的に何を送りますか？

3 つのクエリパラメータを付けた GET リクエストを URL に送ります。hub.mode は subscribe に設定されます。hub.verify_token は、送信先の設定時に指定したトークンです。hub.challenge は、この試行のために Meta が生成する値です。

エンドポイントでは、hub.verify_token と指定したトークンを比較してください。一致した場合は、200 と hub.challenge だけをレスポンスボディ全体として返します。JSON で包まず、値を引用符で囲まず、一部のフレームワークが標準で追加する末尾の改行も付けません。

トークンが一致しない場合は 403 を返します。これがプロトコルのすべてで、意図的に小さく設計されています。

間違った返答はなぜ何も知らせずに失敗しますか？

認証の失敗は、あなたのシステムのエラーではなく、Meta 側で配信が存在しない状態になるためです。

チャレンジが正しく返されないと、Meta はその送信先への配信を開始しません。サーバーは認証に 200 を返し、ログにはリクエストの到着が記録されますが、どのダッシュボードにも問題は表示されません。唯一の症状はメッセージが届かないことです。そのため、多くの人はこれをハンドシェイクの問題ではなく Coexistence の問題だと判断します。

だからこそ、呼び出し前の検証が重要です。EasyCoexistence は Graph リクエストを送る前に、URL が HTTPS であり、認証トークンが指定されていることを確認します。そのため、不正な送信先は接続済みのように見えるのではなく、すぐに失敗します。

ほかに認証を妨げるものはありますか？

コードとは無関係なものが 3 つあります。

エンドポイントの前に認証を置くことです。ゲートウェイ、基本認証レイヤー、IP 許可リストは Meta のリクエストを拒否します。Meta には提示できる認証情報がありません。認証なしで認証ルートに到達できる必要があります。

リダイレクトです。Meta は指定された URL を呼び出しますが、正規ホストへの 301 がハンドシェイクを完了する形で追跡されるとは限りません。最終 URL を指定してください。

そして、レスポンスをシリアライズするフレームワークです。ハンドラーから文字列を返しても、すべてを JSON で包む設定だと、チャレンジが引用符で囲まれたボディになります。その場合は一致しません。

よくある間違い

• JSON を返すこと。ボディは余計なものを付けず、チャレンジの値をそのまま返す必要があります。
• エンドポイントを認証の背後に置くこと。Meta には認証情報がないため、拒否されます。
• リダイレクトする URL を Meta に渡すこと。最終 URL を使用してください。

よくある質問

続きを読む