WhatsApp Webhook の再送、重複、順序:対処方法
Meta は、HTTP 200 以外の応答を受け取った WhatsApp Webhook を、すぐに再送し、その後は間隔を空けながら最長 7 日間再送します。7 日を過ぎると破棄されます。再送は、そのアカウントに登録されたすべてのアプリに届くため、重複は通常起こります。200 を速やかに返し、メッセージ ID、またはステータス ID とステータス値の組み合わせで重複排除し、イベントはそれぞれのタイムスタンプで並べ替えてください。
easyCoexistence は、WhatsApp Business アプリの番号を Coexistence 経由で Meta の Cloud API に接続し、Meta の再配信を自動化が受け取る前に吸収します。
HTTP 200 が返されなかった Webhook を Meta が破棄するまでの再送期間。
Meta は多くの更新を 1 回の POST にまとめて送ります。ただし、まとめ送りは保証されないため、リクエストごとに個別に処理してください。
WhatsApp Webhook の POST が運べる最大のペイロードサイズ。
easyCoexistence が受信メッセージ ID を保持する期間。再配信されたメッセージで自動化が 2 回実行されないようにするためです。
Forward URL への転送 1 件あたりの試行回数。各試行は 2xx の応答を 10 秒待ち、約 33 時間にわたって行われます。
Meta はいつ WhatsApp Webhook を再送しますか?
エンドポイントが HTTP 200 以外のステータスを返した場合、または配信できなかった場合に再送されます。Meta はすぐに再送し、その後は間隔を空けながら 7 日間にわたって数回再送します。それでも確認応答が得られなかったものは、その後破棄されます。再送は、そのフィールドの WhatsApp Business Account に登録されたすべてのアプリに届くため、Meta は通知が重複する可能性があると注意しています。過去の Webhook を取得する API はないため、7 日間の再送期間を過ぎた配信は、お使いのシステムでは失われます。
サーバーが正常でも重複が届くのはなぜですか?
受信側では処理が成功していても、Meta からは失敗に見える場合があるためです。応答前に処理を行うハンドラーは Meta の待機時間を超えることがあり、そうなると Meta は処理済みのものを再送します。リクエストの途中でデプロイによりサーバーが再起動する場合、ロードバランサーが一時的に 502 を返す場合、あるいは 200 ではなく 201 や 204 を返す場合も、失敗として扱われます。さらに、まとめ送りでは 1 回の POST に多くの更新が含まれるため、大きなバッチでタイムアウトが起きると、処理済みの更新を含むバッチ全体が戻ってきます。
どのキーで重複排除すべきですか?
Meta 自身が提供する ID を、イベントの種類ごとに選んでください。1 つのメッセージからは正当に複数の Webhook が生成されるためです。ステータス値を含まないステータスキーでは、delivered が sent の重複と見なされて取りこぼされてしまいます。また、イベントを含まない通話キーでは、通話の最初の段階しか残りません。キーには一意インデックスを設定してください。そうすることで、同じ再送を処理する 2 つのワーカーが、両方とも処理を実行することを防げます:
Webhook はどの順序で届きますか?
必ずしも出来事が起きた順序とは限りません。Meta のドキュメントは順序を保証しておらず、再送された配信は、より新しい配信の後に届きます。また、ステータスは段階を飛ばすことがあります。メッセージが届いた瞬間に既読になった場合、Meta は delivered を送らず read を送るためです。そのため、イベントは独自のタイムスタンプフィールドで保存し、ステータスは到着順ではなく順位で比較してください。遅れて届いた古い顧客メッセージより、後から届いた新しい顧客メッセージを優先します。Coexistence の番号では、初回の履歴インポートがオンボーディング前後にライブのメッセージと重なる場合があり、両者を突き合わせるのはメッセージ ID です。
安全なハンドラーはどのような構成ですか?
検証する、200 を正確に返す、重複排除する、そのうえでキューから処理する、の 4 つです。これにより、Meta のリクエストと自社の応答の間に遅い処理が挟まることがありません。このバージョンでは、ご自身の Meta アプリのシークレットを使って X-Hub-Signature-256 を検証します。easyCoexistence 経由で接続された番号では、Meta は easyCoexistence のアプリシークレットで署名します。そのため、直接の送信先では、代わりに URL パス内の長いシークレットで認証するか、番号ごとに署名される管理された転送に切り替えてください。
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production
// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
const keys = [];
for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
return keys;
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // exactly 200, before any work
const body = JSON.parse(raw.toString("utf8"));
for (const entry of body.entry ?? []) {
for (const change of entry.changes ?? []) {
for (const key of keysOf(change.field, change.value ?? {})) {
if (seen.has(key)) continue; // a retry of something already accepted
seen.add(key);
// queue { key, field: change.field, value: change.value } for a worker here
console.log("new", key);
}
}
}
});
}).listen(process.env.PORT ?? 3000);easyCoexistence は接続済みの番号の再送をどう処理しますか?
受信時には、easyCoexistence は Meta の署名を確認し、200 を返したうえで、応答の後に自動化を実行します。そのため、AI の返信に数秒かかっても、Meta が再送することはありません。受信した各メッセージ ID は 7 日間保持されます。これは Meta の再送期間と同じ長さです。再配信されたメッセージは認識され、自動返信が 2 回実行されることはありません。
お使いのサーバーの Forward URL への送信時には、Meta の各変更が 1 件の配信になり、X-EC-Delivery に含まれる ID は転送の再試行の間も変わりません。試行は約 33 時間にわたって 7 回行われ、各試行は 2xx の応答を 10 秒待ちます。Meta 自身が再配信した変更は、新しい配信 ID で改めて転送されるため、value 内の Meta の ID でも重複排除してください。
よくある間違い
- ID だけでステータスを重複排除すること。sent、delivered、read は同じ wamid を共有するため、キーにはステータス値も含める必要があります。
- 応答より先に処理すること。処理が遅いと、Meta は既に行った作業を再送させます。先に 200 を返し、その後キューから処理してください。
- 201 や 204 を返すこと。Meta のドキュメントは 200 以外のステータスをすべて配信失敗とみなし、再送します。
- X-EC-Delivery だけで転送を重複排除すること。Meta が再配信した変更は新しい配信 ID で届くため、Meta の ID を 2 つ目のキーとして残してください。
そのため、再送されたメッセージに AI の返信が 2 回届くことはありません。サーバーへの転送は署名、キューイング、再試行が行われ、すべての番号は 24 時間体制で監視されます。料金は、接続済みの番号 1 件あたり月額 US$ 9 から、番号を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料です。
よくある質問
確認済みの ID はどのくらい保存すればよいですか?
少なくとも 7 日間です。これは Meta の再送期間と同じです。6 日目に再送された配信も、そのキーと一致しなければならず、一致しないと新規として処理されてしまいます。
エンドポイントが数日間停止した場合、お客様のメッセージはどうなりますか?
Meta は最長 7 日間再送し、その後 Webhook を破棄します。Coexistence の番号では、会話は電話の WhatsApp Business アプリに残っているため、事業者はそこから返信できます。
取りこぼした Webhook を再生できますか?
Meta からは再生できません。過去の Webhook データを取得する API はありません。Coexistence の番号の履歴インポートは、オンボーディング時に一度だけ実行され、同じ接続で再度要求することはできません。
Meta は同じ更新を複数のサーバーに送りますか?
Meta は、そのフィールドの WhatsApp Business Account に登録されたすべてのアプリに送ります。送信先のオーバーライドを設定すると、番号のメッセージフィールドは、そのアプリの既定のコールバックではなく、オーバーライド URL に送られます。
続きを読む
始める準備はできましたか?
WhatsApp Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。
無料トライアルを始める確認日