Endpoints
Create Endpoint | Webhooks API
Create endpoint via the Atoa Webhooks API, request parameters, response schema and code samples in cURL, Python, JavaScript, PHP, Go and Java.
POST
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.
Response
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
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.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.string
Optional label for this endpoint (max 100 characters). Shown in the Atoa Dashboard to help identify the endpoint.
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.
None — no authentication
None — no authentication
Omit the
authentication field entirely. No credentials will be sent with deliveries. Use signature verification to validate requests on your side.Basic Auth — username + password
Basic Auth — username + password
OAuth 2.0 — client credentials flow
OAuth 2.0 — client credentials flow
Before each delivery, Atoa calls your token endpoint using the
client_credentials grant to obtain a short-lived access token, then includes it as Authorization: Bearer <token> in the delivery request. Pass all three fields together.string
required
Client ID registered with your authorisation server.
string
required
Client secret for the above client ID.
string
required
Your token endpoint URL (e.g.
https://auth.your-server.com/oauth/token). Atoa will POST to this URL to fetch an access token before each delivery.string
Unique identifier for the endpoint.
string
The registered endpoint URL.
string
The endpoint description, or
null if not set.string
SANDBOX or PRODUCTION, derived from the API key used.array
Subscribed event types.
boolean
Whether endpoint authentication is configured.
string
BASIC, OAUTH2, or null if no authentication is configured.number
Consecutive failed deliveries since the last successful delivery. Resets to
0 on success.string
ISO 8601 timestamp of the last successful delivery, or
null if never delivered.