添加 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 个字符。
可访问性	必须可从公网访问。回环地址（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 请求头为选填。不带该请求头的调用会正常执行，但不具备防重复的保护。请参阅幂等性。

错误

以下所有失败情况都会返回 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}`
回环、私有网段或 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 与签名验证。

授权

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

合并运货单

通知

回收

重寄

退货库存

退件运货单（创建）

服务类型

退件运货单

退件运货单服务类型

增值服务

仓库

端点要求

端点会收到所有事件

验证请求

已保存的 URL

幂等性

错误

授权

请求体

响应

​端点要求

​端点会收到所有事件

​验证请求

​已保存的 URL

​幂等性

​错误

​相关

授权

请求体

响应

端点要求

端点会收到所有事件

验证请求

已保存的 URL

幂等性

错误

相关