> ## 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 文字以下であること。 | | 到達可能性 | インターネットから到達可能であること。ループバック、プライベートネットワーク、リンクローカルのアドレスは拒否されます。 | | 一意性 | 同一アカウントで既に登録済みの URL でないこと。 | | 上限 | 1 アカウントあたり最大 5 件。アカウントに別の上限が設定されている場合は、エラーメッセージにその値が示されます。 | 上記はすべて検証リクエストの送信前にチェックされるため、拒否されたリクエストが実際にサーバーへ届くことはありません。

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

登録したエンドポイントは、アカウントの**すべての**通知イベントを受信します。Return Helper 側にイベント単位の購読やフィルターの仕組みはありません。 フィルタリングは自社側で行ってください。通知ボディの `category` と `action` フィールドを読み取り、処理しないイベントは無視します。無視する場合でも `2xx` ステータスで応答してください——2xx 以外の応答は配信失敗として扱われ、失敗が続くとエンドポイントへの配信が停止されます。[リトライの仕組み](/ja/webhooks#retry-mechanism)を参照してください。 想定される `action` の値は [Http 通知アクションタイプの取得（ユーザー向け）](/ja/api-reference/notificationactiontype/get-http-notification-action-types-for-users)で確認できます。

検証リクエスト

エンドポイントを保存する前に、Return Helper は指定された URL へ `POST` を送信します。このリクエストには、[ラベル生成](/ja/webhooks#label-result)通知と同じ形のサンプルペイロードと、有効な `ReturnHelper-Signature` を含む[通知ヘッダー](/ja/webhooks#notification-headers)一式が付与されます——そのため、本番稼働前にハンドラーと署名検証を一通り確認できます。 登録が成功するのは、エンドポイントが **30 秒**以内に **2xx** ステータスを返した場合のみです。それ以外のステータス、タイムアウト、DNS 解決失敗、接続拒否、TLS エラーが発生した場合は呼び出しが失敗し、エンドポイントは保存されません。 検証ペイロード内の ID や値はサンプルであり、アカウント内の実在するオブジェクトを指すものではありません。ハンドラーが未知の ID を許容できるようにするか、リクエストを受理してから後続処理を行ってください。 最終的な URL を登録してください。判定に使われるのは最終的な HTTP ステータスのみのため、リダイレクトする URL でも検証を通過することがありますが、サービスが実際に受け取る内容は本番の通知と異なる可能性があります。

保存される URL

レスポンスの `endpoint` は**正規化後**の URL です——Return Helper が実際に保存する文字列であり、以降の重複チェックで比較される文字列でもあります。送信した値と異なる場合があるため、自社の入力値ではなくレスポンスで返された値を保存してください。

冪等性

`x-returnhelper-idempotency-key` ヘッダーは任意です。付与しない呼び出しも通常どおり実行されますが、重複に対する保護はありません。[冪等性](/ja/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}` | | ループバック、プライベートネットワーク、リンクローカルのアドレス | `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 Endpoint を一覧取得](/ja/api-reference/notification/list-notification-endpoints) * [Notification Endpoint を削除](/ja/api-reference/notification/delete-notification-endpoint) * [Webhooks](/ja/webhooks) — イベント一覧、ペイロード、署名の検証。 ## 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 ````