Add a notification endpoint
通知
新增 Notification Endpoint
POST
Add a notification endpoint
註冊一個用於接收 webhook 通知的 HTTPS 端點。Return Helper 會先向該 URL 發送驗證請求,再決定是否儲存——只有在您的端點有回應時,註冊才會成功。
端點要求
以上規則都會在發送驗證請求之前檢查,因此被拒絕的請求不會實際送達您的伺服器。
端點會收到所有事件
已註冊的端點會收到您帳戶的所有通知事件。Return Helper 端不提供逐一事件的訂閱或篩選機制。 請在您端進行篩選:從通知主體讀取category 與 action 欄位,忽略您不處理的事件。即使忽略該事件,仍請回應 2xx 狀態碼——非 2xx 的回應會被視為傳遞失敗,多次失敗會導致您的端點暫停接收通知。請參閱重試機制。
取得 Http 通知動作類型(使用者)列出您可能收到的 action 值。
驗證請求
在儲存端點之前,Return Helper 會向您提供的 URL 發送一次POST。該請求帶有固定的範例 Payload(格式與標籤產生通知相同),以及完整的通知標頭,其中包含有效的 ReturnHelper-Signature——因此您可以在正式上線前,完整驗證您的處理器與簽章驗證流程。
只有當您的端點在 30 秒內回應 2xx 狀態碼時,註冊才會成功。任何其他狀態碼、逾時、DNS 解析失敗、連線被拒或 TLS 錯誤,都會使本次呼叫失敗,且端點不會被儲存。
驗證 Payload 中的 ID 與各項數值皆為範例,並不對應您帳戶中的真實物件。請確保您的處理器能容忍未知的 ID,或先確認收到請求再進行後續處理。
已儲存的 URL
回應中的endpoint 是正規化後的 URL——也就是 Return Helper 實際儲存的字串,以及後續重複檢查所比對的字串。它可能與您提交的值不同,請保存回應中回傳的值,而非您自己的輸入值。
等冪性
x-returnhelper-idempotency-key 標頭為選填。未帶此標頭的呼叫會正常執行,但不具備防重複的保護。請參閱等冪性。
錯誤
以下所有失敗情況都會回傳 HTTP200,meta.status 為 400,meta.errorCode 為 VALIDATION_FAILED,訊息則放在 meta.error.endpoint。
相關
- 列出 Notification Endpoints
- 刪除 Notification Endpoint
- Webhooks — 事件清單、Payload 與簽章驗證。
授權
Your API key
Your API token — keep this private
主體
application/json
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.