顧客の WhatsApp メッセージとソーシャルのコメントを Webhook で受け取る方法
easyCoexistence の Partner API を通じて、接続ごとに顧客の WhatsApp メッセージまたはソーシャルのコメント用の Webhook が 1 つずつ割り当てられます。WhatsApp メッセージは Meta からその URL へ直接届き、お客様が保有するシークレットではなく Tech Provider アプリのシークレットで署名されます。そのため、URL パスに含めた長くランダムなシークレットで認証します。Instagram と Facebook のコメントと DM、そして TikTok のコメントは、届いた時点で転送され、アカウントごとに X-EC-Signature で署名されます。
番号のメッセージをエンドポイントへ送る代替コールバック URL の、Meta が定める最大長。
エンドポイントが受け付けなかった WhatsApp Webhook を、Meta が頻度を減らしながら再試行する期間。重複の原因になることがあります。
Meta のネットワーク。whois のルート照会で、WhatsApp Webhook の送信元アドレスを一覧できます。Meta は定期的に変更します。
Meta によると、WhatsApp Webhook ペイロードの最大サイズ。
署名付きタイムスタンプがこの時間を超えたら拒否すべき経過時間。HMAC は定数時間比較で照合します。
接続ごとの届け先はどう設定するか
リソースごとに 1 回の API 呼び出しで設定します。WhatsApp の番号は、url と verify_token を指定して PUT /connections/{id}/webhook を呼び出すか、接続セッションで webhook_url と webhook_verify_token の組を渡します。これにより、番号は接続直後からお使いのサーバーへ届きます。ソーシャルアカウントは、接続後に PUT /channels/{id}/webhook で設定します。どちらかの url に null を指定すると配信が停止します。2 つの経路は、誰が配信するか、どのように認証するかが異なります。
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
番号のメッセージを自社のエンドポイントへ向けるには
長くランダムなシークレットをパスに含んだ HTTPS の URL を用意し、加えて検証トークンを指定します。接続セッションでは webhook_verify_token(8〜200 文字)、PUT では verify_token を使います。Meta は GET で URL を直ちに確認し、hub.mode=subscribe、hub.verify_token、hub.challenge を送ります。トークンが一致したら、エンドポイントは hub.challenge の値で応答する必要があります。このハンドシェイクが失敗すると、PUT は Meta のメッセージ付きで 502 meta_rejected を返します。接続セッションの場合、番号は接続されたままですが、セッションの last_error に URL が適用されなかった理由が記録されます。
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});Meta の署名を検証できない理由と、その代わりの方法
Meta は配信ごとに X-Hub-Signature-256 で署名します。これは、受信側アプリの App Secret を鍵とする、ペイロードの HMAC-SHA256 です。顧客の番号では、その受信側アプリは easyCoexistence の Tech Provider アプリで、そのシークレットは共有されないため、お使いの側ではヘッダーを検証できません。代わりに、URL パスに含めた長くランダムなシークレットを認証情報として使います。定数時間比較で照合し、それ以外は拒否してください。第 2 の防御層として、Meta の AS32934 に登録された経路を許可リストに登録し、定期的に更新してください。Meta は IP アドレスを定期的に変更するためです。
どの WhatsApp Webhook が URL に届くか
代替コールバック URL に送られるフィールドは次のとおりです。messages は顧客が送ったメッセージと、お使いのアカウントから送ったメッセージのステータス。smb_message_echoes は WhatsApp Business アプリから企業が送ったメッセージ。一回限りのインポートの history と smb_app_state_sync。Meta はテンプレートの Webhook も、account_update などのアカウントの Webhook も、オーバーライドへは送りません。それらは代わりに easyCoexistence のコールバックに届きます。そのため、テンプレートの審査はポーリングで読み取り、却下はステータスイベントとして届きます。
- 届け先は WhatsApp Business Account に設定されるため、1 つのアカウント内の 2 つの番号は同じ届け先を共有します。value.metadata.
phone_number_idでルーティングしてください。 - メディアは ID として届くため、認証情報の呼び出しで得た顧客のトークンを使って、Meta からファイルを取得してください。
- ペイロードは最大 3 MB になることがあるため、3 MB を下回る本文サイズ上限を設定している場合は、引き上げてください。
転送されるソーシャルイベントはどのような形式か
Content-Type が application/json で、X-EC-Signature ヘッダーを持つ POST リクエストです。キーは 4 つあります。platform、account_id(Partner API が使うチャネル ID)、external_id(ネットワーク上のアカウント ID)、entry です。Instagram と Facebook では、entry は Meta の Webhook の entry がそのまま入ります。コメントとメンションは changes に、DM は messaging に入ります。TikTok では、内容がパースされた comment.update イベントが entry に入り、comment_id、video_id、parent_comment_id は文字列として届きます。そのため 64 ビット ID が丸められることはありません。
- Instagram アカウントはコメント、メッセージ、メンションを購読し、Facebook のページはフィード、メッセージ、mention を購読します。TikTok は comment.update を送信します。
- easyCoexistence は YouTube と LinkedIn からコメントイベントを受信しません。これらへの PUT は 400
not_supportedを返します。そのコメントは、認証情報を使って各ネットワークの API から読み取ります。 - 転送には X-EC-Event も X-EC-Delivery ヘッダーも付きません。そのため、コメント ID やメッセージの mid などネットワーク側の ID で重複を排除してください。
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}X-EC-Signature は手順どおりにどう検証するか
PUT /channels/{id}/webhook が返した signing_secret を使います。このシークレットは一度だけ表示され、そのアカウントに固有です。ヘッダーは t=<unix>,v1=<hex> の形式です。配信ごとに、次の手順で検証します。
- JSON として解析する前に、リクエスト本文を生のバイト列として読み取ります。
- ヘッダーをカンマで分割し、秒単位の Unix 時間の t と、16 進数のダイジェストの v1 に分けます。
- t が自社のクロックから 5 分以上ずれている場合は、配信を拒否します。
- t、ドット、生の本文をこの順に連結したものに対し、そのアカウントのシークレットを鍵として HMAC-SHA256 を計算し、16 進数で表します。
- 計算結果を v1 と定数時間比較で照合し、2xx を返してから作業をキューに入れます。
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});届け先が設定されていない場合はどうなるか
何も届かず、後から送られることもありません。webhook_url を持たない番号は easyCoexistence のコールバックに戻り、そのメッセージは保存されずに破棄されます。また、チャット履歴のインポートも受けられません。インポートは届け先が存在するときにのみ要求されるためです。届け先のないソーシャルアカウントは転送されません。そのイベントは easyCoexistence のアプリには届きますが、お使いのために保持されるものはありません。トラフィックが必要になる前に、各届け先を設定してください。
接続が切断されたり削除されたりしたとき、届け先はどうなるか
番号は届け先を記録として保持します。切断された番号が再接続されると、easyCoexistence は Meta に対して再びお使いの URL を設定します。一時停止された番号が復帰したときも同様です。ソーシャルアカウントを削除すると、その届け先とシークレットが消去されます。そのため、再接続後は PUT /channels/{id}/webhook を再度呼び出し、新しいシークレットを保存してください。URL を指定して呼び出すたびに、この PUT は新しいシークレットを発行し、古いシークレットはただちに署名に使われなくなります。
設定方法
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
よくある間違い
- 顧客の WhatsApp 配信で X-Hub-Signature-256 を検証すること。Meta は、共有されない easyCoexistence のアプリシークレットで署名を計算するため、検証は決して通りません。URL パスのシークレットで認証してください。
- パース済みの JSON に対して X-EC-Signature を検証すること。HMAC は生の本文をバイト単位で対象とします。再シリアライズするとバイト列が変わるため、解析の前に検証してください。
- すべてのチャネルで 1 つのシークレットを使うこと。ソーシャルアカウントはそれぞれ固有のシークレットで署名し、ステータスイベントは別のシークレットで署名します。account_id でシークレットを検索してください。
- 転送されたイベントへの応答の前に時間のかかる処理を行うこと。転送は一度だけ送られ、応答を 8 秒待ち、再試行されません。そのため、先に 2xx を返し、その後で処理してください。
easyCoexistence は、顧客の電話番号ごとのメッセージを Meta からお使いのサーバーへ直接届け、Instagram と Facebook のコメントと DM、そして TikTok のコメントを届いた時点でエンドポイントへ転送します。転送はアカウントごとに署名され、コピーは保持せず、すべての接続を 24 時間体制で監視します。料金は接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料です。
よくある質問
顧客の WhatsApp メッセージに Meta の署名を検証できますか?
いいえ。Meta は、共有されない easyCoexistence の Tech Provider アプリのシークレットで署名します。URL パスの長くランダムなシークレットで認証してください。必要に応じて、Meta の IP 範囲も併用できます。
YouTube と LinkedIn の接続は、コメントイベントを転送しますか?
いいえ。easyCoexistence はどちらのコメントイベントも受信しないため、PUT /channels/{id}/webhook は 400 not_supported を返します。コメントは、各ネットワークの API でチャネルの認証情報を使って読み取ってください。
自社のサーバーが停止している場合、転送されたソーシャルイベントは再試行されますか?
いいえ。各イベントは一度だけ送られ、コピーは保持されません。WhatsApp の配信は異なり、Meta 自身が最大 7 日間再試行します。
メッセージは easyCoexistence を経由しますか?
WhatsApp では経由しません。Meta が番号のメッセージを、設定された Webhook へ直接届けます。ソーシャルネットワークのコメントと DM は、届いた時点で、アカウントごとに署名されてエンドポイントへ転送されます。コピーは保持されません。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日