如何透過 Webhook 接收客戶的 WhatsApp 訊息及社交平台留言
每個連接都有自己的 Webhook,用於接收客戶的 WhatsApp 訊息或社交平台留言,經由 easyCoexistence 的 Partner API 傳送。WhatsApp 訊息由 Meta 直接傳送到該 URL,簽署使用的是 Tech Provider 應用程式的密鑰,而非您持有的密鑰,因此 URL 路徑中一組夠長的隨機密鑰就是驗證方式。Instagram 及 Facebook 的留言與私訊,以及 TikTok 的留言,會在到達時即時轉發,並以各帳戶專屬的 X-EC-Signature 簽署。
Meta 對替代回調 URL 所設的最大長度,該 URL 會將號碼的訊息傳送到您的端點。
Meta 重試您端點未接受之 WhatsApp Webhook 的時間長短,重試頻率逐步降低,可能會產生重複訊息。
Meta 的網絡;whois 路由查詢會列出 WhatsApp Webhook 的來源位址,Meta 會定期更改這些位址。
Meta 所定的 WhatsApp Webhook 負載最大容量。
轉發事件的簽署時間戳超過此時限即應拒絕;HMAC 須以常數時間比較。
每個連接如何獲得自己的目的地?
透過每項資源各一次調用。WhatsApp 號碼使用 PUT /connections/{id}/webhook,並提供 url 與 verify_token;或在其連接會話中提供相同組合的 webhook_url 與 webhook_verify_token,使號碼自第一分鐘起即路由至您。社交帳戶連接後,則使用 PUT /channels/{id}/webhook 並提供 url。任一項的 url 設為 null 即會停止傳送。兩條路徑的分別在於由誰傳送,以及您如何驗證:
| 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 會立即以附帶 hub.mode=subscribe、hub.verify_token 及 hub.challenge 的 GET 請求檢查該 URL,權杖相符時,您的端點必須回覆 hub.challenge 的值。若該握手失敗,PUT 會返回 502 meta_rejected 及 Meta 的原始訊息;在連接會話中,號碼仍會連接,而該會話的 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 路徑中的隨機密鑰:請以常數時間比較,並拒絕其他一切請求。作為第二層保護,請將註冊給 Meta AS32934 的路由列入白名單,並定期更新該清單,因為 Meta 會定期更改其 IP 位址。
哪些 WhatsApp Webhook 會傳送到您的 URL?
Meta 允許覆寫 URL 攜帶的欄位包括:messages,用於客戶的來訊及您所發訊息的狀態;smb_message_echoes,用於商家從 WhatsApp Business 應用程式發出的訊息;以及一次性匯入的 history 與 smb_app_state_sync。Meta 從不會將訊息範本 Webhook,或 account_update 等帳戶 Webhook,傳送至覆寫 URL。這些會改為傳送至 easyCoexistence 的回調,因此範本審核須透過輪詢讀取,而遭拒的範本會以狀態事件通知您。
- 目的地設於 WhatsApp Business Account 上,因此同一帳戶內的兩個號碼共用該目的地:請以 value.metadata.
phone_number_id作路由。 - 媒體以 ID 形式傳入;請以客戶的權杖(取自憑證調用)從 Meta 取回檔案。
- 負載可達 3 MB,請把任何低於此值的主體大小上限調高。
轉發的社交事件是什麼樣子?
一個 POST 請求,Content-Type 為 application/json,並附 X-EC-Signature 標頭,包含四個鍵:platform;account_id,即 Partner API 使用的頻道 ID;external_id,即帳戶在該網絡上的 ID;以及 entry。Instagram 及 Facebook 的 entry 保持 Meta 原本的 Webhook entry,留言與提及包含 changes,私訊則為 messaging。TikTok 的 entry 包含已解析內容的 comment.update 事件,並將 comment_id、video_id 與 parent_comment_id 以字串傳送,因此 64 位元 ID 不會被捨入。
- Instagram 帳戶訂閱 comments、messages 及 mentions;Facebook 專頁訂閱 feed、messages 及 mention;TikTok 傳送 comment.update。
- easyCoexistence 不會接收 YouTube 或 LinkedIn 的留言事件:其 PUT 會回應 400
not_supported,您可透過各網絡的 API,配合憑證讀取其留言。 - 轉發時不會附上 X-EC-Event 或 X-EC-Delivery 標頭,因此請以網絡本身的 ID 去重,例如留言 ID 或訊息 mid。
{
"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 解析之前進行。
- 以逗號拆分標頭,取得 t(以秒計的 Unix 時間)及 v1(十六進位摘要)。
- 若 t 與您的時鐘相差超過 5 分鐘,則拒絕該次傳送。
- 以該帳戶的密鑰,對 t、一個句點及原始主體計算 HMAC-SHA256,並以十六進位表示。
- 以常數時間與 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 涵蓋原始主體的每個位元組,重新序列化會改變位元組,因此須先驗證再解析。
- 所有頻道共用一個密鑰。每個社交帳戶以其專屬密鑰簽署,而狀態事件則以另一密鑰簽署,因此請以 account_id 查找密鑰。
- 在回覆轉發的事件前進行耗時工作。事件只會發送一次,等候您回覆 8 秒,且從不重試,因此請先回覆 2xx,之後再處理。
easyCoexistence 將每個客戶號碼的訊息由 Meta 直接路由至您的伺服器,並將 Instagram 及 Facebook 的留言與私訊,以及 TikTok 的留言,在到達時即時轉發至您的端點,以各帳戶專屬的方式簽署,不保留任何副本,並全天候 24/7 監控每項連接。每項連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 天免費。
常見問題
我能否驗證 Meta 在客戶 WhatsApp 訊息上的簽署?
不能。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。社交網絡的留言與私訊則會在到達時轉發至您的端點,以各帳戶專屬的方式簽署,且不保留副本。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期