> ## Documentation Index > Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt > Use this file to discover all available pages before exploring further. # 添加 Notification Endpoint 此页面由 AI 自动翻译。API 技术规格以英文呈现为标准。如有任何疑问，请参阅[英文版本](/api-reference/notification/add-notification-endpoint)。 注册一个用于接收 webhook 通知的 HTTPS 端点。Return Helper 会先向该 URL 发送验证请求，再决定是否保存——只有在您的端点作出响应时，注册才会成功。

端点要求

| 规则 | 说明 | | ---- | -------------------------------------------------- | | 协议 | 仅接受 `https`。 | | 长度 | 规范化后不得超过 255 个字符。 | | 可访问性 | 必须可从公网访问。回环地址（loopback）、私有网段地址与 link-local 地址会被拒绝。 | | 唯一性 | 该 URL 不得是您的账户已注册过的 URL。 | | 数量上限 | 每个账户最多 5 个端点。若您的账户配置了不同的上限，错误消息会标明该数值。 | 以上规则都会在发送验证请求之前检查，因此被拒绝的请求不会实际到达您的服务器。

端点会收到所有事件

已注册的端点会收到您账户的**所有**通知事件。Return Helper 端不提供按事件订阅或筛选的机制。 请在您端进行筛选：从通知主体读取 `category` 与 `action` 字段，忽略您不处理的事件。即使忽略该事件，也请返回 `2xx` 状态码——非 2xx 的响应会被视为投递失败，多次失败会导致您的端点暂停接收通知。请参阅[重试机制](/zh-Hans/webhooks#retry-mechanism)。 [获取 Http 通知动作类型（用户）](/zh-Hans/api-reference/notificationactiontype/get-http-notification-action-types-for-users)列出您可能收到的 `action` 值。

验证请求

在保存端点之前，Return Helper 会向您提供的 URL 发送一次 `POST`。该请求带有固定的示例 Payload（格式与[标签生成](/zh-Hans/webhooks#label-result)通知相同），以及完整的[通知请求头](/zh-Hans/webhooks#notification-headers)，其中包含有效的 `ReturnHelper-Signature`——因此您可以在正式上线前，完整验证您的处理器与签名校验流程。 只有当您的端点在 **30 秒**内返回 **2xx** 状态码时，注册才会成功。任何其他状态码、超时、DNS 解析失败、连接被拒或 TLS 错误，都会使本次调用失败，且端点不会被保存。 验证 Payload 中的 ID 与各项数值均为示例，并不对应您账户中的真实对象。请确保您的处理器能容忍未知 ID，或先确认收到请求再进行后续处理。 请注册最终的 URL。系统只判读最终的 HTTP 状态码，因此会跳转的 URL 也可能通过验证，但您的服务实际收到的内容可能与正式通知不同。

已保存的 URL

响应中的 `endpoint` 是**规范化后**的 URL——也就是 Return Helper 实际保存的字符串，以及后续重复检查所比对的字符串。它可能与您提交的值不同，请保存响应中返回的值，而不是您自己的输入值。

幂等性

`x-returnhelper-idempotency-key` 请求头为选填。不带该请求头的调用会正常执行，但不具备防重复的保护。请参阅[幂等性](/zh-Hans/introduction#idempotency)。

错误

以下所有失败情况都会返回 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}.` | ```json theme={null} { "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](/zh-Hans/api-reference/notification/list-notification-endpoints) * [删除 Notification Endpoint](/zh-Hans/api-reference/notification/delete-notification-endpoint) * [Webhooks](/zh-Hans/webhooks) — 事件列表、Payload 与签名验证。 ## OpenAPI ````yaml post /api/Notification/Add openapi: 3.1.0 info: title: Return Helper API description: API documentation for Return Helper — covering User and Public endpoints. version: 1.0.0 servers: - url: https://api.returnshelper.com/uat/user description: Sandbox — User API - url: https://api.returnshelper.com/uat/public description: Sandbox — Public API - url: https://api.returnhelpercentre.com/v1/user description: Production — User API - url: https://api.returnhelpercentre.com/v1/public description: Production — Public API - url: https://api.returnhelperchina.com/user description: Production — User API (China) security: - ApiKey: [] ApiToken: [] paths: /api/Notification/Add: post: tags: - Notification summary: Add a notification endpoint operationId: ReturnUserApi_NotificationAdd requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddNotificationRequest' responses: '200': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/General_NotificationEndpointReply' '401': description: >- Authentication failed. Returned when the `x-rr-apikey` or `x-rr-apitoken` header is missing or invalid. The body uses the standard `ApiResponse` envelope with `meta.error.message` describing the auth failure. content: application/json: schema: $ref: '#/components/schemas/ApiResponse' security: - ApiKey: [] ApiToken: [] servers: - url: https://api.returnshelper.com/uat/user description: Sandbox — User API components: schemas: AddNotificationRequest: type: object properties: endpoint: type: string description: >- 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. examples: - https://acme.example/hooks/returnhelper required: - endpoint General_NotificationEndpointReply: type: object properties: data: $ref: '#/components/schemas/NotificationEndpointReply' ApiResponse: type: object description: >- Universal response envelope. Successful responses include the business payload as additional top-level fields alongside `correlationId` and `meta`. Failed responses (auth errors, validation errors) only populate `correlationId` and `meta`, with `meta.errorCode` and `meta.error` describing the failure. properties: correlationId: type: - string - 'null' description: >- Unique correlation ID for tracing the request through Return Helper systems. meta: $ref: '#/components/schemas/ApiResponseMeta' NotificationEndpointReply: type: object properties: apiNotificationId: type: integer format: int64 description: >- Identifier of the registered notification endpoint. Pass this to /api/Notification/Delete. examples: - 1234 endpoint: type: - string - 'null' description: The normalized endpoint URL as stored by Return Helper. examples: - https://acme.example/hooks/returnhelper ApiResponseMeta: type: object description: >- Application-level metadata for every API response. Inspect `status` and `errorCode` to detect soft-error responses (validation failures arrive as HTTP 200 with `meta.status: 400`). properties: status: type: integer description: >- Application-level status code. For successful operations this mirrors the HTTP status (e.g. 200). For validation failures it reports the logical status (e.g. 400) even though the wire HTTP status is 200. data: type: object additionalProperties: type: string description: Reserved free-form metadata key/value pairs. Usually empty. errorCode: type: - string - 'null' description: >- Machine-readable error code (e.g. `VALIDATION_FAILED`). Non-null only when the operation failed. error: type: object additionalProperties: true description: >- Field-level or message-level error detail keyed by request property name. Empty object on success. securitySchemes: ApiKey: type: apiKey in: header name: x-rr-apikey description: Your API key ApiToken: type: apiKey in: header name: x-rr-apitoken description: Your API token — keep this private ````