Facebook Webhook の検証:hub.challenge と X-Hub-Signature-256
Facebook は、hub.mode に subscribe を設定し、hub.verify_token と hub.challenge を付けた GET リクエストで Webhook エンドポイントを検証します。エンドポイントは、トークンを App Dashboard の値と照合し、チャレンジ値を本文として返します。その後、各イベントは X-Hub-Signature-256 で署名された POST として届きます。その値は sha256= に続けて、ペイロードの HMAC-SHA256 を、アプリシークレットを鍵として計算したものです。
easyCoexistence は、接続する Page ごとに Meta 側の処理を担当します。
Meta の検証リクエストで hub.mode が必ず持つ値。hub.challenge は返送する整数です。
X-Hub-Signature-256 の接頭辞で、Meta がペイロードとアプリシークレットから生成する SHA256 署名が続きます。
Messenger の Webhook エンドポイントが、各通知に 200 OK で応答すべき速さ。
「Webhooks Disabled」アラートが出され、アプリが Page から購読解除されるまでの、配信失敗の回数。
Meta が失敗した Page 通知を、頻度を減らしながら再試行し、破棄するまでの期間。
Meta の検証リクエストには何が含まれますか?
Webhooks 製品が App Dashboard で設定されたとき、または /{app-id}/subscriptions を通じてサブスクリプションが作成されたときに、コールバック URL へ GET が送られます。これには 3 つのクエリパラメータが付きます:
- hub.mode:常に subscribe です。
- hub.challenge:エンドポイントが返さなければならない整数です。
- hub.
verify_token:App Dashboard の「Verify Token」フィールドに入力された文字列です。 - PHP はドットをアンダースコアに変換するため、
hub_mode、hub_challenge、hub_verify_tokenとして読み込まれます。
エンドポイントはどのように応答すればよいですか?
hub.mode が subscribe で、hub.verify_token が一致する場合に限り、本文が hub.challenge の値だけの 200 を返します。それ以外には、Meta のサンプルアプリと同様に 403 を返します。App Dashboard は、エンドポイントが検証に合格したかどうかを報告し、/{app-id}/subscriptions は成功またはエラーを返します。エンドポイントには、有効な TLS または SSL 証明書を備えた HTTPS が必要です。自己署名証明書は、サポートされていません。
X-Hub-Signature-256 はどのように計算されますか?
アプリシークレットを鍵とした、リクエストペイロードの HMAC-SHA256 で、sha256= の後に小文字の 16 進数で記述されます。Meta の Messenger ガイドには、署名はユニコードエスケープされたペイロードを対象とすると記載されています。そのため、äöå のような文字列は \u00e4\u00f6\u00e5 として数えられます。受信したままの生の本文をハッシュしてください。デコードや再シリアライズしたコピーは使用しないでください。Meta は検証を任意としていますが、強く推奨しています。
コードでどのように確認しますか?
生のバイト列を保持し、HMAC を計算して、定数時間で比較してから、解析します。Flask の get_data は本文を変更せずに返すため、署名の計算元となったものと一致します。先に解析してから再シリアライズすると、バイト列が変わってしまいます。検証に応答し、各 POST を確認する小さなエンドポイントは次のとおりです:
import hashlib, hmac, os
from flask import Flask, abort, request
app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()
@app.get("/webhooks/facebook")
def verify():
token = request.args.get("hub.verify_token", "")
if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
return request.args.get("hub.challenge", ""), 200
abort(403)
@app.post("/webhooks/facebook")
def receive():
raw = request.get_data() # the bytes Meta signed
expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
abort(401)
# answer at once; hand request.get_json() to a queue for the work
return "EVENT_RECEIVED", 200検証後、Meta は何を求めていますか?
Messenger のイベントには 5 秒以内に、各通知に対して 200 OK を返すことを期待しています。Meta は配信ごとに最大 1,000 件の更新をまとめて送ることがありますが、保証はされていません。失敗の扱いは次のとおりです:
- Page の通知:すぐに再試行され、その後 36 時間かけて頻度を減らしながら数回再試行され、破棄されます。
- Messenger の通知:すぐに数回再試行されます。15 分間失敗が続くと、デベロッパーアカウントにアラートが届きます。
- 1 時間失敗が続くと「Webhooks Disabled」アラートが送られ、アプリが再び購読するまで Page から購読解除されます。
- 再試行によってイベントが 2 回届いたり、順序が入れ替わったりすることがあるため、重複を排除し、メッセージをタイムスタンプで並べ替えてください。
- 過去の通知は後から照会できないため、届いた時点で必要なデータを保存してください。
easyCoexistence はどのように Meta の検証に対応していますか?
easyCoexistence の Meta アプリは、接続するすべての Page に対して 1 つのコールバック URL を持ち、そのエンドポイントが両方の確認を自ら行います。hub.mode が subscribe で、検証トークンが一致する場合にのみ GET に応答し、定数時間で比較します。それ以外は 403 を返します。各 POST は生のテキストとして読み取り、アプリシークレットで X-Hub-Signature-256 を再計算します。不一致は 401 で拒否します。イベントの処理は応答の後に行うため、Meta にはすぐに応答します。
easyCoexistence は転送するイベントにどのように署名しますか?
独自の署名を付けます。Meta の署名ヘッダーは easyCoexistence のアプリシークレットでしか確認できず、転送されないためです。接続済みで、エンドポイントが設定されている Page の各エントリは、JSON として次の形式で POST されます:{platform, account_id, external_id, entry}。X-EC-Signature ヘッダーは t=<unix>,v1=<hex> の形式で付きます。v1 は、タイムスタンプ、ドット、生の本文の HMAC-SHA256 で、その Page の署名シークレットを鍵としたものです:
- シークレットは whsec_ で始まり、Partner API の
set_social_webhook_destinationまたは PUT /channels/:id/webhook で一度だけ表示されます。 - URL を再設定すると新しいシークレットが発行され、URL を null にすると転送がオフになります。
- 各転送は 1 回だけ送信され、最大 8 秒待機し、リダイレクトは追跡せず、パブリック IP に解決される HTTPS アドレスに送られます。
- イベントのコピーは保持されないため、再試行の元となるものはありません。
X-EC-Signature はどのように検証しますか?
ヘッダーを t と v1 に分割し、5 分より古いタイムスタンプは拒否してください。次に、t、ドット、生の本文の HMAC を、その Page の署名シークレットで再計算し、定数時間で比較します。Node.js では、本文を生のバイト列として保持した状態で、次のように行います:
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once
app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
);
const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
const expected = crypto
.createHmac("sha256", SECRET)
.update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
.digest("hex");
const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
if (!ok) return res.sendStatus(401);
res.sendStatus(200); // answer first: forwards are not retried
const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
// queue entry for the work
});よくある間違い
- hub.challenge を JSON や引用符で囲むこと。200 の本文は、チャレンジ値そのものでなければなりません。
- JSON パーサーの後で HMAC を計算すること。解析と再シリアライズでバイト列が変わり、Meta はユニコードエスケープされたペイロードに署名するため、生の本文をハッシュしてください。
- 応答の前に処理を行うこと。Messenger は 5 秒以内の 200 を期待しており、1 時間の失敗でアプリが Page から購読解除されます。
- 転送されたイベントで Meta の署名を確認すること。Meta は easyCoexistence のアプリシークレットで署名します。転送されたイベントには X-EC-Signature が付いており、Page の署名シークレットで確認します。
アプリが hub.challenge に応答し、X-Hub-Signature-256 を確認して、Page のフィード、メッセージ、メンションを購読します。その後、イベントを、その Page 用のシークレットで署名された X-EC-Signature 付きで、指定した HTTPS エンドポイントに転送します。接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料です。
よくある質問
検証トークンはどこで決めますか?
自分で決めます。App Dashboard で Webhook を設定する際の「Verify Token」フィールドに入力する文字列、または /{app-id}/subscriptions に送る verify_token です。
curl で検証をテストできますか?
はい。Meta の Messenger ガイドでは、hub.verify_token、hub.challenge=CHALLENGE_ACCEPTED、hub.mode=subscribe を付けた GET を送ります。正しく動作しているエンドポイントは CHALLENGE_ACCEPTED を返します。
エンドポイントが 1 時間失敗したらどうなりますか?
Meta が「Webhooks Disabled」アラートを送り、アプリを Page から購読解除します。エンドポイントを修正したら、subscribed_apps で Page をもう一度購読してください。
Page の Webhook を受け取るには、自分の Meta アプリが必要ですか?
easyCoexistence を使う場合は不要です。Meta は easyCoexistence のアプリに配信し、そのアプリが各 Page のイベントを、指定したエンドポイントに X-EC-Signature で署名して転送します。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日