Add a notification endpoint
curl --request POST \
--url https://api.returnshelper.com/uat/user/api/Notification/Add \
--header 'Content-Type: application/json' \
--header 'x-rr-apikey: <api-key>' \
--header 'x-rr-apitoken: <api-key>' \
--data '
{
"endpoint": "https://acme.example/hooks/returnhelper"
}
'import requests
url = "https://api.returnshelper.com/uat/user/api/Notification/Add"
payload = { "endpoint": "https://acme.example/hooks/returnhelper" }
headers = {
"x-rr-apikey": "<api-key>",
"x-rr-apitoken": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-rr-apikey': '<api-key>',
'x-rr-apitoken': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({endpoint: 'https://acme.example/hooks/returnhelper'})
};
fetch('https://api.returnshelper.com/uat/user/api/Notification/Add', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.returnshelper.com/uat/user/api/Notification/Add",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'endpoint' => 'https://acme.example/hooks/returnhelper'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-rr-apikey: <api-key>",
"x-rr-apitoken: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.returnshelper.com/uat/user/api/Notification/Add"
payload := strings.NewReader("{\n \"endpoint\": \"https://acme.example/hooks/returnhelper\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-rr-apikey", "<api-key>")
req.Header.Add("x-rr-apitoken", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.returnshelper.com/uat/user/api/Notification/Add")
.header("x-rr-apikey", "<api-key>")
.header("x-rr-apitoken", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"endpoint\": \"https://acme.example/hooks/returnhelper\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.returnshelper.com/uat/user/api/Notification/Add")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-rr-apikey"] = '<api-key>'
request["x-rr-apitoken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"endpoint\": \"https://acme.example/hooks/returnhelper\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"apiNotificationId": 1234,
"endpoint": "https://acme.example/hooks/returnhelper"
}
}{
"correlationId": "<string>",
"meta": {
"status": 123,
"data": {},
"errorCode": "<string>",
"error": {}
}
}通知
新增 Notification Endpoint
POST
/
api
/
Notification
/
Add
Add a notification endpoint
curl --request POST \
--url https://api.returnshelper.com/uat/user/api/Notification/Add \
--header 'Content-Type: application/json' \
--header 'x-rr-apikey: <api-key>' \
--header 'x-rr-apitoken: <api-key>' \
--data '
{
"endpoint": "https://acme.example/hooks/returnhelper"
}
'import requests
url = "https://api.returnshelper.com/uat/user/api/Notification/Add"
payload = { "endpoint": "https://acme.example/hooks/returnhelper" }
headers = {
"x-rr-apikey": "<api-key>",
"x-rr-apitoken": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-rr-apikey': '<api-key>',
'x-rr-apitoken': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({endpoint: 'https://acme.example/hooks/returnhelper'})
};
fetch('https://api.returnshelper.com/uat/user/api/Notification/Add', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.returnshelper.com/uat/user/api/Notification/Add",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'endpoint' => 'https://acme.example/hooks/returnhelper'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-rr-apikey: <api-key>",
"x-rr-apitoken: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.returnshelper.com/uat/user/api/Notification/Add"
payload := strings.NewReader("{\n \"endpoint\": \"https://acme.example/hooks/returnhelper\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-rr-apikey", "<api-key>")
req.Header.Add("x-rr-apitoken", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.returnshelper.com/uat/user/api/Notification/Add")
.header("x-rr-apikey", "<api-key>")
.header("x-rr-apitoken", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"endpoint\": \"https://acme.example/hooks/returnhelper\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.returnshelper.com/uat/user/api/Notification/Add")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-rr-apikey"] = '<api-key>'
request["x-rr-apitoken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"endpoint\": \"https://acme.example/hooks/returnhelper\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"apiNotificationId": 1234,
"endpoint": "https://acme.example/hooks/returnhelper"
}
}{
"correlationId": "<string>",
"meta": {
"status": 123,
"data": {},
"errorCode": "<string>",
"error": {}
}
}此頁面由 AI 自動翻譯。API 技術規格以英文呈現為標準。如有任何疑問,請參閱英文版本。
端點要求
| 規則 | 說明 |
|---|---|
| 通訊協定 | 僅接受 https。 |
| 長度 | 正規化後不得超過 255 個字元。 |
| 可連線性 | 必須可從公開網際網路連線。回送位址(loopback)、私有網段位址與 link-local 位址會被拒絕。 |
| 唯一性 | 該 URL 不得為您的帳戶已註冊過的 URL。 |
| 數量上限 | 每個帳戶最多 5 個端點。若您的帳戶設定了不同的上限,錯誤訊息會標示該數值。 |
端點會收到所有事件
已註冊的端點會收到您帳戶的所有通知事件。Return Helper 端不提供逐一事件的訂閱或篩選機制。 請在您端進行篩選:從通知主體讀取category 與 action 欄位,忽略您不處理的事件。即使忽略該事件,仍請回應 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 標頭為選填。未帶此標頭的呼叫會正常執行,但不具備防重複的保護。請參閱等冪性。
錯誤
以下所有失敗情況都會回傳 HTTP200,meta.status 為 400,meta.errorCode 為 VALIDATION_FAILED,訊息則放在 meta.error.endpoint。
| 條件 | 訊息 |
|---|---|
| 並非有效的絕對 URL | Invalid URL format: {endpoint} |
| 超過 255 個字元 | Endpoint must be 255 characters or fewer. |
| 通訊協定不是 HTTPS | Endpoint must use HTTPS. Received scheme: {scheme} |
| 回送、私有網段或 link-local 位址 | Endpoint must be publicly reachable. Private, loopback and link-local addresses are not allowed. |
| 該帳戶已註冊過此 URL | This endpoint is already registered. |
| 帳戶已達數量上限 | Maximum 5 endpoints allowed. Delete an existing endpoint before adding a new one. |
| 驗證請求回傳非 2xx 狀態碼 | Endpoint returned {statusCode} ({statusCodeNumber}). It must return a 2xx status to be registered. |
| 逾時未回應 | Endpoint did not respond within 30 seconds. |
| 無法解析主機名稱 | Could not resolve host: {host} |
| 連線被拒或中斷 | Could not connect to {host}. Check that the service is running and that our requests are not blocked. |
| TLS 憑證驗證失敗 | TLS certificate validation failed for {host}. |
{
"correlationId": "0HNCJ2K1P9RQ4:00000003",
"meta": {
"status": 400,
"data": {},
"errorCode": "VALIDATION_FAILED",
"error": {
"endpoint": "Maximum 5 endpoints allowed. Delete an existing endpoint before adding a new one."
}
}
}
相關
- 列出 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.
Show child attributes
Show child attributes