SNS Webhook 旁路（LINE 等外部 SNS 的 Webhook 轉發）

ReceiptRoller 會接收店鋪串接的外部 SNS（LINE 官方帳號、Meta、X 等）所送來的 Webhook，利用於自動回覆與活動處理。這些原始事件，只要有店鋪端明示的許可，開發者即可將其原封不動轉發至已登錄的端點。這就是「SNS Webhook 旁路」。

在這種情況下使用

• 想將 LINE 官方帳號的訊息匯入自家 CRM
• 想從追蹤事件啟動獨自的 onboarding 處理
• 想利用貼文回呼製作獨自的抽獎串接
• 想將 SNS 的提及、回覆通知至公司內工具

是在需要超出 ReceiptRoller 端自動回覆功能可實現範圍的、獨自業務邏輯時的選項。

機制

[LINE / Meta / X 等]
        │ Webhook（平台表單簽章附帶）
        ▼
[ReceiptRoller 接收端點]
        │ ① 驗證平台表單簽章
        │ ② 自家的業務處理（自動回覆、彙總等）
        │ ③ 旁路設定為 ON 則轉發至開發者端點
        ▼
[開發者應用程式]
        ・以 X-RR-Source-Platform 可知發送來源 SNS
        ・以 X-RR-Original-Signature 可確認原始簽章
        ・以 X-RR-Signature 也附帶 ReceiptRoller 的簽章

ReceiptRoller 只是「中繼而已」，轉發的酬載內容維持 SNS 端的原始形式。LINE 的 Webhook 就是 LINE 的 JSON，Meta 就是 Meta 的 JSON 原封不動送達。藉此，開發者可將各 SNS 的官方 SDK 或文件原封不動沿用。

設定方法（由店鋪管理者實施）

旁路需要在店鋪端明示地啟用。開發者請向店鋪管理者說明本頁的步驟。

1. 登入 ReceiptRoller 管理畫面
2. 左選單「商業帳戶」→「SNS 帳戶」
3. 開啟該 SNS 帳戶（例：LINE 官方帳號）的「編輯」
4. 開啟「Webhook 旁路」區段
5. 將「啟用旁路」切換為 ON
6. 選擇作為轉發對象的開發者應用程式（需事先登錄應用程式）
7. 選擇要轉發的事件種類（例：message、follow、postback）
8. 點擊「儲存」

轉發時的標頭

簽章的驗證

接收端可依用途驗證 2 種簽章。

方法 A：驗證 ReceiptRoller 的簽章（建議）

以與通常的 ReceiptRoller Webhook 相同的方式驗證 X-RR-Signature。因為驗證邏輯可統一為 1 個，運用會變簡單。詳情請參照簽章驗證與安全性。

方法 B：驗證原始的 SNS 簽章

因為本文是 SNS 端的原始形式，也可以使用各 SNS 的 SDK 驗證原始的簽章（X-RR-Original-Signature）。想將 LINE 官方 SDK 的範例程式碼原封不動沿用時等很方便。但這種情況下，需要開發者保有 SNS 端的頻道密鑰。

接收範例（LINE）

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-RR-Source-Platform: line
X-RR-Source-Account-Id: sns_a1b2c3
X-RR-Original-Signature: aXyZ...（LINE 發行的簽章）
X-RR-Signature: 9f8e7d...（RR 發行的 HMAC）
X-RR-Timestamp: 1745740000
X-RR-Event-Id: evt_01HV6N...

{
  "destination": "U1234567890...",
  "events": [
    {
      "type": "message",
      "message": { "type": "text", "id": "...", "text": "こんにちは" },
      "timestamp": 1745739999000,
      "source": { "type": "user", "userId": "U..." },
      "replyToken": "..."
    }
  ]
}

本文部分是從 LINE 接收到的原封不動，因此可原封不動傳給 LINE Messaging API SDK 的 WebhookParser 等。

關於回覆的注意

旁路中，開發者端點只要回傳 2xx 即可，回覆訊息等請從開發者端直接呼叫 SNS API發送。ReceiptRoller 不中繼回覆。

• 使用 LINE 的 replyToken 時，由開發者直接 POST 至 LINE Messaging API
• 為此，需要另行處理店鋪的 LINE 頻道存取權杖
• 取得方法依店鋪調整（平台表單授權流程，或從店鋪手動共享）

重送、冪等性

轉發事件也與通常的 Webhook 相同，若非 2xx 則最多重送 7 次。請務必實作以 event_id 進行的冪等性檢查。詳情請參照重送、順序、冪等性的設計。

作為注意點，即使 SNS 端的原始 Webhook 已先在其他頻道（自動回覆處理等）處理完的情況下，旁路也會獨立地轉發。請將雙方分別設計。

限制事項

• 對應平台：LINE、Meta（Facebook/Instagram）、X、TikTok、YouTube、Pinterest、LinkedIn、GBP（依序擴大中）
• 每 1 個 SNS 帳戶，轉發對象應用程式最多 1 個
• 轉發的事件種類僅限 SNS 端發生者。不含 ReceiptRoller 獨自事件
• 旁路在Starter 方案以上可利用
• 轉發延遲的參考為通常 1 秒以內（平台表單接收後）

安全性與隱私權上的注意

• 轉發的本文中，含有 LINE 使用者 ID、訊息本文等個人資訊
• 需要在店鋪端的隱私權政策，明記對外部開發者的轉發
• 開發者端也請在與店鋪的契約中明確化接收資料的保管、利用範圍
• 測試時建議使用專用的測試用 SNS 帳戶，避免處理真實顧客資料

相關指南

• Webhook 的概要
• 簽章驗證與安全性
• 重送、順序、冪等性的設計
• 監視與失敗時的對應
• 返回開發者幫助中心