WhatsApp のメッセージがサーバーに届く仕組み:直接か、マネージドか、署名の検証
easyCoexistence で接続した番号ごとに、受信モードを一つ選べます。自社システムへ直接(ダイレクト):Meta が Webhook を自社の HTTPS エンドポイントへ送信します。URL 内のシークレットが認証情報となり、オートメーションはオフです。easyCoexistence 経由(マネージド):Meta の配信先は easyCoexistence になり、オートメーションが応答できます。任意で転送先 URL を設定すると、Meta の元の値と接続情報が届きます。その内容は X-EC-Signature で署名されるため、受信側で検証できます。
転送 1 件につき、1 分、5 分、30 分、2 時間、6 時間、24 時間の間隔で再試行され、合計は約 33 時間です。
各転送の試行が 2xx の応答を待つ時間。この時間を過ぎると失敗として扱われます。
署名内の t の経過時間に対する推奨上限です。再試行も再署名されるため、正規の配信はこの範囲に収まります。
HTTP 200 以外の応答を受けた直接 Webhook を、Meta が再試行する期間です。メッセージが重複する場合があります。
履歴のチャンクを含め、Meta が送る Webhook ペイロードの最大サイズです。
マネージド番号の実行ログは、メッセージと返信の本文とともに保存されます。メッセージ本文自体は、30 日、90 日、365 日から選んだ期間保存されます。
直接とマネージドの違いは何ですか?
Meta が番号のメッセージ Webhook をどこへ配信するかの違いです。マネージド(画面上では「easyCoexistence 経由」と表示されます)では、Meta は easyCoexistence へ配信します。easyCoexistence は Meta の署名を確認し、オートメーションを実行し、Conversations 用にチャットを保存し、転送先 URL を設定している場合は Meta の各変更を、あなただけが持つシークレットで署名して渡します。直接(画面上では「自社システムに直接送信」と表示されます)では、easyCoexistence が番号の WhatsApp Business Account 上の Webhook オーバーライドとして自社の HTTPS エンドポイントを設定します。Meta から直接届くため、メッセージは easyCoexistence を経由しません。
監視を支える運用 Webhook(account_update や品質の変更など)は、どちらのモードでも easyCoexistence が受け取ります。そのためアラートはいずれの場合も動作し続けます。
| Managed: Through easyCoexistence | Direct: Straight to your system | |
|---|---|---|
| Meta delivers to | easyCoexistence, which verifies Meta's signature | Your HTTPS endpoint |
| Automations | Run on the number | Off |
| Your copy | Optional Forward URL, one Meta change per POST | Meta's envelope, unchanged |
| Proof it is genuine | X-EC-Signature, HMAC-SHA256 with the number's secret | A long random secret in the URL path |
| Failed deliveries | 7 attempts over about 33 hours | Meta retries for up to 7 days |
| History import | Not requested | Requested when saved within 24 hours of connecting |
| Kept by easyCoexistence | Message text 30, 90 or 365 days, run logs 30 days | Nothing |
番号のモードはどのように切り替えますか?
番号のページにある「受信メッセージの送信先」カードでは、モードが「easyCoexistence 経由」と「自社システムに直接送信」の 2 つの選択肢で表示されます。「受信メッセージを自社の Webhook へ送る」カードで Webhook の送信先を保存するか、set_webhook_destination を使うと、番号は直接モードになります。「easyCoexistence 経由」を選ぶと、その送信先は Meta 側から直ちに削除されます。受信を続けるには、同じ URL を転送先 URL として追加してください。番号がマネージドモードを離れると、キューに入っている転送は破棄されます。Webhook URL なしで接続された番号は、マネージドから始まります。
お使いの AI から set_inbound_mode を呼び出すと、モードの切り替えと転送先の設定を一度に行え、転送シークレットは一度だけ返されます:
// set_inbound_mode arguments
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward"
}
// result: forward_secret is shown once
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward",
"forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
"secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
"direct_destination": null
}転送された POST には何が含まれますか?
リクエストごとに Meta の変更が 1 件ずつ含まれ、Meta の object、entry、changes のエンベロープではなく、ラップされた形式です。id は配信 ID で、X-EC-Delivery にも同じ値が入り、再試行をまたいでも変わりません。event は Meta のフィールド名(messages、smb_message_echoes、history、smb_app_state_sync のいずれか)で、X-EC-Event にも入ります。received_at は easyCoexistence が Meta から変更を受け取った時刻、connection は番号を示し、value は Meta が送った内容そのままです。そのため Meta のペイロード向けに書かれた解析コードがそのまま動作します。配信ステータスは messages イベントの value.statuses 内に届きます。
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>
{
"id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
"event": "messages",
"received_at": "2026-11-11T14:02:11.482Z",
"connection": {
"id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"phone": "+1 631-555-0142",
"phone_number_id": "106540352242922",
"waba_id": "102290129340398",
"external_ref": null
},
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
"contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
"messages": [{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
"timestamp": "1794405731",
"type": "text",
"text": { "body": "Do you deliver on Sundays?" }
}]
}
}Node.js で X-EC-Signature を検証するにはどうすればよいですか?
ヘッダーを t=<Unix 秒>,v1=<64 文字の 16 進数> として読み取ります。自社のクロックと 5 分以上ずれた t は拒否します。t、ドット、生のボディを連結した文字列に対して、転送シークレット全体を UTF-8 テキストとして鍵にし、HMAC-SHA256 を計算します。結果と v1 を定数時間比較で照合します。その後に初めて JSON を解析します。10 秒以内に 2xx を返し、処理はその後に行ってください。受け付けた配信 ID を保存しておくと、再試行を二重に処理せずに済みます。
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production
export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
if (!m || !secret) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // a 2xx within 10 s, before any work
const d = JSON.parse(raw.toString("utf8"));
if (taken.has(d.id)) return; // a retry of a delivery already accepted
taken.add(d.id);
// d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
// d.value is Meta's change value, unchanged; queue it for your worker here.
console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
});
}).listen(process.env.PORT ?? 3000);Python ではどのように検証しますか?
標準ライブラリだけで、同じ 4 つのチェックを行います。ヘッダーの厳密なパターン照合、t の経過時間の確認、t、ドット、生のバイト列に対する hmac.new、そして hmac.compare_digest です。FastAPI では生のボディを await request.body() から取得し、BackgroundTasks で 200 を送信した後に処理を実行します。Flask では request.get_data() を使い、json.dumps でボディを組み立て直さないでください。Python の既定の区切り文字が空白を追加するため、署名が一致しなくなります。
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response
app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode() # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set() # delivery ids already accepted: use a database in production
def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
m = SIGNATURE.fullmatch(header.strip())
if not m or abs(int(time.time()) - int(m[1])) > max_age:
return False
mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, m[2])
def process(delivery: dict) -> None:
if delivery["id"] in taken: # a retry of a delivery already accepted
return
taken.add(delivery["id"])
print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))
@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
raw = await request.body()
if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
return Response(status_code=401)
tasks.add_task(process, json.loads(raw)) # runs after the 200 goes out
return Response(status_code=200)失敗した配信はどのように再試行されますか?
転送は、自社のエンドポイントが 10 秒以内に任意の 2xx を返すと配信済みとみなされます。それ以外(タイムアウト、4xx、5xx、または追跡されないリダイレクト)の場合は、次の試行を約 1 分、5 分、30 分、2 時間、6 時間、24 時間後に予約します。7 回目の試行の後、その配信は破棄されます。各試行は新しい t で再署名されます。転送先 URL は公開の HTTPS である必要があり、保存時と送信のたびに確認されます。配信は古いものから順に送られますが、再試行された配信は新しい配信の後に届くことがあるため、Meta のタイムスタンプで並べ替えてください。
直接の送信先では Meta が再試行を行います。HTTP 200 以外は、最長 7 日間にわたり頻度を減らしながら再試行されます。この再試行によりメッセージが重複する場合があります。両モードとも Meta のメッセージ ID で重複排除してください。Meta が再配信した変更は、新しい配信 ID で再び転送されるためです。
直接の送信先で、POST が本物かどうかはどう確認しますか?
X-Hub-Signature-256 では確認できません。Meta は、その購読を所有するアプリのアプリシークレットで署名します。ここで接続された番号の場合、それは easyCoexistence のものであり共有されていません。そのため、自社の Meta アプリシークレットでこのヘッダーを確認すると、正規の配信を拒否してしまいます。検証トークンは、Meta の GET によるハンドシェイク時に一度だけエンドポイントを確認するためのものです。代わりに有効な方法は次のとおりです:
- コールバック URL のパスに 32 文字以上のランダムな文字列を含め、それがないリクエストは拒否してください。ローテーションするには新しい URL を保存します。
- 自社の Meta アプリを前提とする WhatsApp トリガーではなく、n8n の Webhook ノードなどの汎用受信処理を使ってください。
- メディアは、番号のトークンを使って ID を指定し Meta からダウンロードしてください。偽造された ID は単に失敗します。
- 自前でサーバーを運用している場合は、必要に応じて Meta のネットワーク(AS32934 が公表するルート)のみを許可できます。
- または、転送先 URL を設定してマネージドに切り替えてください。その場合、X-EC-Signature が各 POST を証明します。
よくある間違い
- Meta のエンベロープ向けに書かれたコードを、転送先 URL にそのまま向けないことです。転送は変更を 1 件だけ含みます。object、entry、changes ではなく、event と value を読んでください。
- X-EC-Event が statuses になるのを待つことです。配信ステータスは messages イベントの value.statuses に含まれ、アプリで入力された返信は smb_message_echoes として届きます。
- 応答より先に処理を行うことです。転送は 10 秒待機し、その後、同じ配信が新しい t で再送されます。先に 2xx を返し、キューから処理してください。
- マネージドに切り替えた後も古い URL が受信すると思い込むことです。直接の送信先はその時点で削除されます。同じ set_inbound_mode の呼び出しで forward_url を渡してください。
easyCoexistence は、WhatsApp Business アプリの番号を Coexistence 経由で Meta の Cloud API に接続し、番号ごとにメッセージの送り先を選べます。Meta から自社サーバーへ直接送るか、easyCoexistence を経由してオートメーションで応答し、署名付きのコピーを転送先 URL に届けるかを選択できます。監視とアラートは、どちらのモードでも動作します。料金は接続済みの番号 1 件あたり月額 US$ 9 から、番号を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料トライアルです。
よくある質問
自社サーバーは、オートメーションの返信内容を見られますか?
テキストは見られません。Meta は API による送信を、メッセージ ID とともに messages イベント内のステータス(sent、delivered、read)として報告します。返信のテキスト自体は、オートメーションの実行ログにあり、「実行」タブに 30 日間保存されます。また Conversations には、選んだ期間保存されます。
転送シークレットはどのようにローテーションしますか?
番号のページで「新しいシークレット」をクリックするか、rotate_secret を true に設定して set_inbound_mode を呼び出します。新しいシークレットは一度だけ表示され、以後のすべての署名に使われます。古い配信の再試行も含まれるため、すぐにサーバーを更新してください。
転送先 URL には Meta の GET ハンドシェイクが必要ですか?
いいえ。Meta が呼び出し、hub.challenge を返す必要があるのは直接の送信先だけです。転送先 URL は easyCoexistence が呼び出し、署名付きの POST だけを受け取ります。
一つの番号で直接の送信先と転送先 URL を同時に設定できますか?
いいえ。転送先 URL はその番号がマネージドのときだけ機能し、直接の送信先を保存すると番号は直接になります。転送先 URL とそのシークレットは保持されるため、マネージドに戻すと転送が再開されます。
続きを読む
始める準備はできましたか?
WhatsApp Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。
無料トライアルを始める確認日