POST
/
api
/
webhook
/
v2
/
endpoints
curl --request POST \
  --url https://api.atoa.me/api/webhook/v2/endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-server.com/webhooks",
    "events": ["PAYMENTS_STATUS", "REFUND_STATUS"],
    "description": "Production orders endpoint"
  }'

{
  "id": "4a124f25-fe8d-47a0-92c8-16d94cbfe24c",
  "url": "https://your-server.com/webhooks",
  "description": "Production orders endpoint",
  "environment": "PRODUCTION",
  "events": [
    { "event": "PAYMENTS_STATUS", "label": "Payment Status" },
    { "event": "REFUND_STATUS", "label": "Refund Status" }
  ],
  "hasAuthentication": false,
  "authenticationType": null,
  "failureCount": 0,
  "lastDeliveredAt": null
}

Register a webhook endpoint and subscribe to one or more event types in a single call. Use List event types to get the full list of available event type names.

Initial registration only. Use this endpoint to register a new URL with its initial event subscriptions. To change events or authentication on an existing endpoint, use Update endpoint. To change the URL, delete the endpoint and create a new one.

​
Authorization

Bearer <token>

Request Body Schema

url
string
required

The HTTPS endpoint URL that will receive webhook deliveries. Must return HTTP 200 on success — failures are retried with exponential back-off for up to 24 hours. This URL cannot be changed after creation — to use a different URL, delete the endpoint and create a new one.

events
string[]
required

One or more event types to subscribe to. Valid values: PAYMENTS_STATUS, EXPIRED_STATUS, REFUND_STATUS, POS_PAYMENT_STATUS. Subscribing to POS_PAYMENT_STATUS requires a webhook signing key to be generated first.

Each event type supports a maximum of 3 registered endpoints. If an event type already has 3 endpoints, adding another endpoint subscribed to that event returns a 400 error. Use List endpoints to check current registrations before creating.

description
string

Optional label for this endpoint (max 100 characters). Shown in the Atoa Dashboard to help identify the endpoint.

authentication
object

Optional. Credentials Atoa will include in every webhook delivery to authenticate against your server. Two methods are supported — choose one. Fields from different methods cannot be mixed.

Response

id
string

Unique identifier for the endpoint.

url
string

The registered endpoint URL.

description
string

The endpoint description, or null if not set.

environment
string

SANDBOX or PRODUCTION, derived from the API key used.

events
array

Subscribed event types.

hasAuthentication
boolean

Whether endpoint authentication is configured.

authenticationType
string

BASIC, OAUTH2, or null if no authentication is configured.

failureCount
number

Consecutive failed deliveries since the last successful delivery. Resets to 0 on success.

lastDeliveredAt
string

ISO 8601 timestamp of the last successful delivery, or null if never delivered.

WebhookUpdate endpoint