> ## 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.
# Add a notification endpoint
Registers an HTTPS endpoint to receive webhook notifications. Return Helper sends a verification request to the URL before storing it — registration succeeds only if your endpoint answers.
## Endpoint requirements
| Rule | Detail |
| ------------ | ----------------------------------------------------------------------------------------------------------------- |
| Scheme | `https` only. |
| Length | 255 characters or fewer, measured after normalization. |
| Reachability | Must be publicly reachable. Loopback, private-network and link-local addresses are rejected. |
| Uniqueness | The URL must not already be registered by your account. |
| Limit | Up to 5 endpoints per account. If your account is configured with a different limit, the error message states it. |
All of the above are checked before the verification request is sent, so a rejected request never reaches your server.
## The endpoint receives every event
A registered endpoint receives **all** notification events for your account. There is no per-event subscription or filter on the Return Helper side.
Filter on your side: read the `category` and `action` fields from the notification body and ignore the events you do not handle. Acknowledge every request with a `2xx` status even when you ignore it — a non-2xx response counts as a failed delivery and repeated failures suspend delivery to your endpoint. See [Retry Mechanism](/webhooks#retry-mechanism).
[Get HTTP notification action types for users](/api-reference/notificationactiontype/get-http-notification-action-types-for-users) lists the `action` values you can expect.
## Verification request
Before the endpoint is stored, Return Helper sends a `POST` to the URL you supplied. It carries a fixed sample payload in the shape of a [label generated](/webhooks#label-result) notification and the complete set of [notification headers](/webhooks#notification-headers), including a valid `ReturnHelper-Signature` — so your handler and your signature check can be exercised end to end before you go live.
Registration succeeds only if your endpoint returns a **2xx** status within **30 seconds**. Any other status, a timeout, a DNS failure, a refused connection or a TLS error fails the call, and the endpoint is not stored.
The IDs and values in the verification payload are samples — they do not refer to real objects in your account. Make sure your handler tolerates unknown IDs, or acknowledge the request before processing it.
Register the final URL. Only the final HTTP status is evaluated, so a URL that redirects can pass verification even though what your service receives may differ from a live notification.
## The stored URL
The `endpoint` value in the response is the **normalized** URL — the exact string Return Helper stores, and the string later duplicate checks compare against. It can differ from what you submitted. Keep the returned value, not your own input.
## Idempotency
The `x-returnhelper-idempotency-key` header is optional. A call without it runs normally, with no protection against duplicates. See [Idempotency](/introduction#idempotency).
## Errors
Every failure below arrives as HTTP `200` with `meta.status` `400`, `meta.errorCode` `VALIDATION_FAILED`, and the message under `meta.error.endpoint`.
| Condition | Message |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Not a valid absolute URL | `Invalid URL format: {endpoint}` |
| Longer than 255 characters | `Endpoint must be 255 characters or fewer.` |
| Scheme is not HTTPS | `Endpoint must use HTTPS. Received scheme: {scheme}` |
| Loopback, private-network or link-local address | `Endpoint must be publicly reachable. Private, loopback and link-local addresses are not allowed.` |
| Already registered by your account | `This endpoint is already registered.` |
| Account is at the maximum | `Maximum 5 endpoints allowed. Delete an existing endpoint before adding a new one.` |
| Verification request returned a non-2xx status | `Endpoint returned {statusCode} ({statusCodeNumber}). It must return a 2xx status to be registered.` |
| No response within the timeout | `Endpoint did not respond within 30 seconds.` |
| Host could not be resolved | `Could not resolve host: {host}` |
| Connection refused or dropped | `Could not connect to {host}. Check that the service is running and that our requests are not blocked.` |
| TLS certificate validation failed | `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."
}
}
}
```
## Related
* [List notification endpoints](/api-reference/notification/list-notification-endpoints)
* [Delete a notification endpoint](/api-reference/notification/delete-notification-endpoint)
* [Webhooks](/webhooks) — event list, payloads and signature verification.
## 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
````