API 開發手冊
遇到問題了嗎?不用擔心,答案都在這。
全站搜尋

Webhook簽章

簽章的用途

為了確保 Webhook 請求確實來自Ragic、且內容未被竄改,設定為「發送更改記錄的完整內容」的 Webhook,發出的請求會附帶一個 signature。

您可以在接收到 Webhook 後,使用我們提供的公鑰驗證該簽章是否正確。

若驗證失敗,表示該請求可能已被竄改,建議拒絕處理。

驗證流程

1. 取得 string-to-sign

1.1. 取出 Webhook 請求中的 data 屬性。 (data 屬性應該為 JSONArray 格式)

1.2. 將其序列化為 按照 key 名字排序無縮排無換行 的 JSON 字串。可以理解為「將JSONArray中,物件的所有欄位依照字母順序重新排序,然後輸出一行 JSON」。

// 轉換前 (原始 data 屬性):
[
  {
    "1001030":"banana",
    "1001029":"apple"
  }
]



// 轉換後 (string-to-sign):
[{"1001029":"apple","1001030":"banana"}]

注意:若序列化方式與我們不一致,會導致簽章驗證失敗。

2. 驗證簽章

2.1. 取出 Webhook 請求中的 signature 屬性。

2.2. 下載公鑰(參考 取得公鑰)。

2.3. 使用支援 SHA256withRSA 的驗簽工具。

  1. 將 string-to-sign 轉換為 UTF-8 byte array
  2. 使用公鑰與演算法驗證簽章

2.4. 驗證結果若為成功,表示請求來自Ragic且內容未被竄改。

取得公鑰

我們提供兩種方式供您取得公鑰,請選擇最適合您的情境:

1. 直接取得公鑰字串,請呼叫:https://www.ragic.com/api/http/getWebhookSignaturePublicKey.jsp?type=string。

2. 點擊 這裡 下載 PEM 檔。

建議將公鑰快取在您的伺服器上,僅在啟動時重新下載。

其他注意事項

  • 若您使用私有主機版,或未啟用「發送更改記錄的完整內容」功能,Webhook 將不支援簽章驗證。
  • 請確保您的程式正確處理 JSON 序列化的一致性,否則會出現驗證錯誤。

提供回饋給 Ragic

請告訴我們您的意見:(多選, 必填)

請針對上方勾選項目提供詳細說明:

截圖能夠讓我們更清楚了解您的建議:

感謝您的寶貴意見!

馬上註冊
免費試用 Ragic!

用 Google 帳號註冊

立即科技 Ragic, Inc.
02-7728-8692
info@ragic.com
台北市中正區南昌路二段81號9樓
使用者條款 | 隱私權政策