Webhooks（又稱 reverse APIs）讓你可以輕鬆打造與貝殼集器緊密整合的服務。Webhooks 可以在安裝在指定的專案上，並且隨時切換開關。當已經建立的交易訂單在未來每一次狀態改變時，將會觸發 Webhooks 事件並發送 HTTP POST request 到你所設定的 URL。

透過 Webhooks 將可以即時傳送交易訂單通知到自己的備份系統；透過你自己的通知系統發送客製化的通知信給客戶；也可以串接至經營團隊的共用通訊頻道，例如 Slack、Telegram，以隨時掌握最新消息。

你可以為每一個專案，同時啟用最多 3 個 Webhooks。

Webhooks 欄位資料請參考此篇文章：Webhooks 資料欄位說明。

一、建立 Webhooks

建立 Webhooks 只需要兩個步驟：

準備一台可以公開接收 JSON request 的伺服器
在指定專案新增 webhook 設定

1. 準備一台可以公開接收 JSON request 的伺服器

為了讓這個教學順利進行，我們推薦 2 種測試方式，可以依照你的需求選擇適合其中一種方案：

你可以先使用 https://webhook.site/ 服務來進行初步的流程測試（如果使用此服務做測試，我們強烈建議另外在 Backme 貝殼集器上建立新的測試專案來進行 webhook 測試，並且全程使用非正式個人資料，Backme 貝殼集器並不對第三方測試工具所搜集的個人資料負責）。
在本地建立一台 localhost 伺服器來接收從 Backme 貝殼集器傳送的 JSON request 訊息。首先需要公開本地的伺服器環境到外部網際網路上，我們建議使用 ngrok（免費、跨平台），詳細的安裝以及使用方式可以參考 ngrok 官方文件說明，如果設定成功應該可以看到終端機的啟動 ngrok 的過程出現類似以下的訊息：

$ Forwarding http://3b2ac1ae.ngrok.io -> 127.0.0.1:4567

其中的 *.ngrok.io 便是需要用來建置 Backme 貝殼集器 webhook 的 URL。

2021.12.2 更新：

若接收位置使用 Let's Encrypt 的免費憑證，有可能發生傳輸失敗的狀況。
承上，接收位置建議使用自行購買的 SSL 憑證。

2. 在指定專案新增 webhook 設定

你可以為指定的專案新增 Webhooks，請點擊專案上方導覽列的「Webhooks」頁籤，然後點擊「新增 webhook」按鈕。

在正式讓 webhook 正確運作之前，還需要填寫一些選項，我們將在以下一一介紹每個需要設定的資料。

a. 名稱

為你的 webhook 提供一個好辨識的名稱，例如：如果這個 webhook 用於傳遞交易的成功訊息到 Slack 上，你可以為它命名「Slack 交易成功通知」，方便未來辨識每個 webhook 的用途。

b. Payload URL

Payload URL 用來接收貝殼集器 Backme 傳送的 POST request 的 URL 位置。

請填入上段章節所推薦的 2 種方式的接收端伺服器的網址。

c. 金鑰

Webhook 金鑰可以確保收到的 POST request 訊息是來自貝殼集器 Backme。

當你設定了金鑰，所有的 POST request headers 都會包含 X-Backme-Signature 標記，貝殼集器 Backme 使用 HMAC 十六進位計算雜湊值，所以你可以用同個方式對 request body 進行雜湊驗算，以下以 Ruby 程式碼為例：

digest = OpenSSL::Digest.new('sha1')
signature = OpenSSL::HMAC.hexdigest(digest, secret, request_json_string)

請注意：貝殼集器 Backme 的 webhook 所發送的 payload 可能包含 unicode 字元，請務必確保你的伺服器處理 payload 時使用的是 UTF-8。

d. 啟用

預設的 webhook 啟用狀態是開啟的，你可以反選「啟用」的勾選框來關閉這個 webhook，貝殼集器 Backme 將不再傳送 request 訊息到這個 webhook 所設定的主機位置。注意：同時啟用的 webhooks 最多只能 3 個。

二、測試 Webhooks

伺服器準備完畢，並且建立好 webhook，可以開始上架回饋 / 商品 / 票券，並且完成結帳。

貝殼集器 Backme 將在以下的訂單狀態時，觸發 webhook 傳送事件：

建立訂單
繳款成功
付款失敗
全額退款
部分退款
消費者從查詢資料前台變更「訂單資訊」時，包含以下
- 客製化選項欄位
- 備註欄位
- 收件人資料
  
  （管理員從後台調整是不會發送 webhook 的）

關於發送的內容 schema 我們將使用 Content-Type application/json 格式，詳細資訊請參考 webhook schema 章節。

1. 列出最近的發送紀錄

在每個 webhook 的正下方，會列出該 webhook 最近的發送紀錄，我們還會列出所有已經發送出去的發送紀錄。

貝殼集器 Backme 只會列出最近的 50 筆資料。

2. 檢視每個發送紀錄的 request 內容

每個發送紀錄旁都有個「展開」按鈕，點擊展開將顯示更多這筆發送紀錄的詳細內容，包括 headers 以及 payload body 內容。這些資訊對於除錯很有幫助。

3. 重新發送指定的發送紀錄

每個發送紀錄都可以重新再發送一次一模一樣的內容。這個功能建議只有用在補發，或是測試用途，不建議在正常的情況下對同一個發送紀錄進行重新發送。