> ## 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-Hant/webhooks#retry-mechanism)。 [取得 Http 通知動作類型（使用者）](/zh-Hant/api-reference/notificationactiontype/get-http-notification-action-types-for-users)列出您可能收到的 `action` 值。

驗證請求

在儲存端點之前，Return Helper 會向您提供的 URL 發送一次 `POST`。該請求帶有固定的範例 Payload（格式與[標籤產生](/zh-Hant/webhooks#label-result)通知相同），以及完整的[通知標頭](/zh-Hant/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-Hant/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-Hant/api-reference/notification/list-notification-endpoints) * [刪除 Notification Endpoint](/zh-Hant/api-reference/notification/delete-notification-endpoint) * [Webhooks](/zh-Hant/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 ````