> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithatoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create webhook event

> Create webhook event via the Atoa Webhooks API, request parameters, response schema and code samples in cURL, Python, JavaScript, PHP, Go and Java.

> [!WARNING]
>
> **v1 Legacy API** — This endpoint registers a single event type per call. Authentication configuration is not supported in v1 — use the [v2 Create Endpoint](https://docs.paywithatoa.com/api-reference/webhook/v2/create-endpoint.md) to configure authentication, subscribe to multiple events per endpoint, and manage endpoints with full CRUD.

Register a webhook endpoint for a specific event type. Each event type requires a separate subscription. See the [Webhook introduction](https://docs.paywithatoa.com/api-reference/webhook/introduction.md) for event types and signature verification.

### Authorization

Bearer `<token>`

**Request Body Schema**

**url** `string` *required*

The endpoint URL that will receive webhook notifications. Must return HTTP 200 on success — failed deliveries are retried with exponential back-off.

**event** `string` *required*

The event type to subscribe to: `PAYMENTS_STATUS`, `EXPIRED_STATUS`, `REFUND_STATUS`, `POS_PAYMENT_STATUS`, or `PAYMENT_METHOD_STATUS`.

**Response**

**webhookId** `string`

Unique identifier for this webhook subscription. Use this value to delete the subscription via `DELETE /api/webhook/{webhookId}/merchant`.

**url** `string`

The registered webhook URL.

**event** `string`

The subscribed event type.

```bash Curl theme={null}
  curl --request POST \
  --url https://api.atoa.me/api/webhook/merchant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://api/endpoint",
  "event": "PAYMENTS_STATUS"
}'
```

```python Python theme={null}

import requests

url = "https://api.atoa.me/api/webhook/merchant"

payload = {
    "url": "https://api/endpoint",
    "event": "PAYMENTS_STATUS"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

```

```javaScript javaScript theme={null}
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"url":"https://api/endpoint","event":"PAYMENTS_STATUS"}'
};

fetch('https://api.atoa.me/api/webhook/merchant', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

```

```php PHP theme={null}
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.atoa.me/api/webhook/merchant",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\n  \"url\": \"https://api/endpoint\",\n  \"event\": \"PAYMENTS_STATUS\"\n }",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```Go Go theme={null}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.atoa.me/api/webhook/merchant"

	payload := strings.NewReader("{\n  \"url\": \"https://api/endpoint\",\n  \"event\": \"PAYMENTS_STATUS\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```java Java theme={null}
HttpResponse<String> response = Unirest.post("https://api.atoa.me/api/webhook/merchant")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"https://api/endpoint\",\n  \"event\": \"PAYMENTS_STATUS\"\n}")
  .asString();
```

```json 200 theme={null}
{
  "webhookId": "4a124f25-fe8d-47a0-92c8-16d94cbfe24c",
  "url": "https://example.com",
  "event": "PAYMENTS_STATUS"
}
```

```json 400 (Missing URL) theme={null}
{
  "name": "AJV_VALIDATION_ERROR",
  "message": "Bad request on parameter request.body.WebhookDataModel must have required property 'url'. Given value: undefined",
  "status": 400,
  "errors": [
    {
      "instancePath": "",
      "schemaPath": "required",
      "keyword": "required",
      "params": {
        "missingProperty": "url"
      },
      "message": "must have required property 'url' ",
      "modelName": "WebhookDataModel",
      "dataPath": ""
    }
  ]
}
```

```json 400 (POS without signing secret) theme={null}
{
  "name": "BAD_REQUEST",
  "message": "POS Payment Status requires V2 signing. Please generate a signing secret from the dashboard to proceed.",
  "status": 400
}
```

```json 401 theme={null}
{
  "name": "UNAUTHORIZED",
  "message": "Unauthorized",
  "status": 401,
  "errors": "[]"
}
```

```json 404 theme={null}
{
  "name": "NOT_FOUND",
  "message": "Webhook not found",
  "status": 404,
  "errors": "[]"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.