> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/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](/api-reference/Webhook/v2/createEndpoint) to configure authentication, subscribe to multiple events per endpoint, and manage endpoints with full CRUD.
</Warning>

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

### Authorization

Bearer `<token>`

**Request Body Schema**

<ParamField body="url" type="string" required>
  The endpoint URL that will receive webhook notifications. Must return HTTP 200 on success — failed deliveries are retried with exponential back-off.
</ParamField>

<ParamField body="event" type="string" required>
  The event type to subscribe to: `PAYMENTS_STATUS`, `EXPIRED_STATUS`, `REFUND_STATUS`, or `POS_PAYMENT_STATUS`.
</ParamField>

**Response**

<ResponseField name="webhookId" type="string">
  Unique identifier for this webhook subscription. Use this value to delete the subscription via `DELETE /api/webhook/{webhookId}/merchant`.
</ResponseField>

<ResponseField name="url" type="string">
  The registered webhook URL.
</ResponseField>

<ResponseField name="event" type="string">
  The subscribed event type.
</ResponseField>

<RequestExample>
  ```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();
  ```
</RequestExample>

<ResponseExample>
  ```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": "[]"
  }
  ```
</ResponseExample>