Skip to main content
POST
Add a notification endpoint
此頁面由 AI 自動翻譯。API 技術規格以英文呈現為標準。如有任何疑問,請參閱英文版本
註冊一個用於接收 webhook 通知的 HTTPS 端點。Return Helper 會先向該 URL 發送驗證請求,再決定是否儲存——只有在您的端點有回應時,註冊才會成功。

端點要求

以上規則都會在發送驗證請求之前檢查,因此被拒絕的請求不會實際送達您的伺服器。

端點會收到所有事件

已註冊的端點會收到您帳戶的所有通知事件。Return Helper 端不提供逐一事件的訂閱或篩選機制。 請在您端進行篩選:從通知主體讀取 categoryaction 欄位,忽略您不處理的事件。即使忽略該事件,仍請回應 2xx 狀態碼——非 2xx 的回應會被視為傳遞失敗,多次失敗會導致您的端點暫停接收通知。請參閱重試機制 取得 Http 通知動作類型(使用者)列出您可能收到的 action 值。

驗證請求

在儲存端點之前,Return Helper 會向您提供的 URL 發送一次 POST。該請求帶有固定的範例 Payload(格式與標籤產生通知相同),以及完整的通知標頭,其中包含有效的 ReturnHelper-Signature——因此您可以在正式上線前,完整驗證您的處理器與簽章驗證流程。 只有當您的端點在 30 秒內回應 2xx 狀態碼時,註冊才會成功。任何其他狀態碼、逾時、DNS 解析失敗、連線被拒或 TLS 錯誤,都會使本次呼叫失敗,且端點不會被儲存。
驗證 Payload 中的 ID 與各項數值皆為範例,並不對應您帳戶中的真實物件。請確保您的處理器能容忍未知的 ID,或先確認收到請求再進行後續處理。
請註冊最終的 URL。系統只會判讀最終的 HTTP 狀態碼,因此會轉址的 URL 也可能通過驗證,但您的服務實際收到的內容可能與正式通知不同。

已儲存的 URL

回應中的 endpoint正規化後的 URL——也就是 Return Helper 實際儲存的字串,以及後續重複檢查所比對的字串。它可能與您提交的值不同,請保存回應中回傳的值,而非您自己的輸入值。

等冪性

x-returnhelper-idempotency-key 標頭為選填。未帶此標頭的呼叫會正常執行,但不具備防重複的保護。請參閱等冪性

錯誤

以下所有失敗情況都會回傳 HTTP 200meta.status400meta.errorCodeVALIDATION_FAILED,訊息則放在 meta.error.endpoint

授權

x-rr-apikey
string
header
必填

Your API key

x-rr-apitoken
string
header
必填

Your API token — keep this private

主體

application/json
endpoint
string
必填

HTTPS URL to receive webhook notifications. Maximum 255 characters after normalization, must be publicly reachable, and must answer the verification request with a 2xx status within 30 seconds.

範例:

"https://acme.example/hooks/returnhelper"

回應

Success — data carries the stored endpoint and its identifier. The endpoint value is the normalized URL that Return Helper stored, which can differ from the submitted value.

data
object