Notification Endpoint を追加

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": {}
  }
}

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技術仕様は英語が正式です。不明点がある場合は英語版を参照してください。

webhook 通知を受信する HTTPS エンドポイントを登録します。Return Helper は保存前に対象 URL へ検証リクエストを送信します——登録が成功するのは、エンドポイントが応答した場合のみです。

エンドポイントの要件

ルール	内容
スキーム	`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 ヘッダーは任意です。付与しない呼び出しも通常どおり実行されますが、重複に対する保護はありません。冪等性を参照してください。

エラー

以下の失敗はいずれも HTTP 200、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 — イベント一覧、ペイロード、署名の検証。

承認

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

Show child attributes

概要

API

FBA

混載配送

通知

リコール

再送

返品在库

返品配送（作成）

サービスタイプ

返品配送

配送サービスタイプ

付加価値サービス

倉庫

Notification Endpoint を追加

エンドポイントの要件

エンドポイントはすべてのイベントを受信します

検証リクエスト

保存される URL

冪等性

エラー

承認

ボディ

レスポンス

​エンドポイントの要件

​エンドポイントはすべてのイベントを受信します

​検証リクエスト

​保存される URL

​冪等性

​エラー

​関連

承認

ボディ

レスポンス

エンドポイントの要件

エンドポイントはすべてのイベントを受信します

検証リクエスト

保存される URL

冪等性

エラー

関連