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 文字以下であること。 |
| 到達可能性 | インターネットから到達可能であること。ループバック、プライベートネットワーク、リンクローカルのアドレスは拒否されます。 |
| 一意性 | 同一アカウントで既に登録済みの URL でないこと。 |
| 上限 | 1 アカウントあたり最大 5 件。アカウントに別の上限が設定されている場合は、エラーメッセージにその値が示されます。 |
エンドポイントはすべてのイベントを受信します
登録したエンドポイントは、アカウントのすべての通知イベントを受信します。Return Helper 側にイベント単位の購読やフィルターの仕組みはありません。 フィルタリングは自社側で行ってください。通知ボディのcategory と action フィールドを読み取り、処理しないイベントは無視します。無視する場合でも 2xx ステータスで応答してください——2xx 以外の応答は配信失敗として扱われ、失敗が続くとエンドポイントへの配信が停止されます。リトライの仕組みを参照してください。
想定される action の値は Http 通知アクションタイプの取得(ユーザー向け)で確認できます。
検証リクエスト
エンドポイントを保存する前に、Return Helper は指定された URL へPOST を送信します。このリクエストには、ラベル生成通知と同じ形のサンプルペイロードと、有効な ReturnHelper-Signature を含む通知ヘッダー一式が付与されます——そのため、本番稼働前にハンドラーと署名検証を一通り確認できます。
登録が成功するのは、エンドポイントが 30 秒以内に 2xx ステータスを返した場合のみです。それ以外のステータス、タイムアウト、DNS 解決失敗、接続拒否、TLS エラーが発生した場合は呼び出しが失敗し、エンドポイントは保存されません。
検証ペイロード内の 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} |
| ループバック、プライベートネットワーク、リンクローカルのアドレス | 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 Endpoint を一覧取得
- Notification Endpoint を削除
- Webhooks — イベント一覧、ペイロード、署名の検証。
承認
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