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

# Subscribe to events

PaySway manages webhooks through **webhook subscriptions**, each of which has its own callback URL, event filter, and other optional metadata to help you organize and secure your integrations. This guide shows you how to create and manage webhook subscriptions.

## Create a webhook subscription

To register a webhook subscription, send the following request describing your new webhook:

[**POST** /webhooks/subscriptions](/api-reference/webhooks/create-webhook-subscription)

**Request parameters:**

<ParamField body="title" type="string" required>
  The label to help you distinguish one webhook from another.
</ParamField>

<ParamField body="url" type="string" required>
  The HTTPS endpoint URL where events are delivered. Important constraints:

  * **URL Scheme:** Only HTTPS is supported
  * **Host Requirement:** The host portion must be a valid domain name (IP addresses are not allowed)
  * **No Redirects:** Your endpoint must not respond with HTTP `3xx` codes
</ParamField>

<ParamField body="events" type="array" required>
  The list of event types you want to receive webhooks for. Providing an empty event types list means no events will be delivered to that subscription.
</ParamField>

<ParamField body="enabled" type="boolean">
  Whether the subscription should be enabled immediately. Defaults to `true`.
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "title": "Verifications webhook",
    "enabled": true,
    "url": "https://tenant.tld/webhooks",
    "events": [
      "ACCOUNT_VERIFICATION_SUBMITTED",
      "ACCOUNT_VERIFICATION_COMPLETED",
      "ACCOUNT_VERIFICATION_FAILED"
    ]
  }
  ```

  ```json Response theme={null}
  {
    "id": "0d4373d7-f2d4-4f30-8660-c53109a38a9c",
    "createdDate": "2025-09-19T11:19:55.194333Z",
    "title": "Verifications webhook",
    "enabled": true,
    "url": "https://tenant.tld/webhooks",
    "events": [
      "ACCOUNT_VERIFICATION_SUBMITTED",
      "ACCOUNT_VERIFICATION_COMPLETED",
      "ACCOUNT_VERIFICATION_FAILED"
    ],
    "secret": "H6lXEzR+0mt3PBrVvp4N6cTUYOJCM60Frk1qpmx4vXM="
  }
  ```
</CodeGroup>

**Response fields:**

<ResponseField name="id" type="string" required>
  Unique identifier for the webhook subscription.
</ResponseField>

<ResponseField name="createdDate" type="string (date-time)" required>
  The date and time the subscription was created, formatted as ISO 8601.
</ResponseField>

<ResponseField name="title" type="string" required>
  The title you provided for the subscription.
</ResponseField>

<ResponseField name="enabled" type="boolean" required>
  Whether the subscription is currently enabled and will receive events.
</ResponseField>

<ResponseField name="url" type="string" required>
  The endpoint URL where events will be delivered.
</ResponseField>

<ResponseField name="events" type="array" required>
  List of event types this subscription will receive.
</ResponseField>

<ResponseField name="secret" type="string" required>
  The signing secret for verifying webhook requests. This is only returned once at creation time.
</ResponseField>

<Warning>
  The `secret` field is critical for [verifying signatures of webhook requests](/webhooks/verify-requests). This secret is only returned once at the time of creation, so be sure to save it in a secure location. If you lose the secret, you will need to create a new subscription.
</Warning>

## Enable and disable subscriptions

You can control whether a subscription actively receives events using the `enabled` field.
Webhook subscriptions are created enabled by default and will immediately start receiving events unless you explicitly set `enabled: false` during creation.

<Steps>
  <Step title="Create disabled subscription">
    Set `enabled: false` in your creation request to create a subscription that won't immediately start receiving events.

    [**POST** /webhooks/subscriptions](/api-reference/webhooks/create-webhook-subscription)

    ```json Request theme={null}
    {
      "title": "Test webhook",
      "enabled": false,
      "url": "https://tenant.tld/webhooks",
      "events": ["ACCOUNT_VERIFICATION_SUBMITTED"]
    }
    ```
  </Step>

  <Step title="Enable when ready">
    Use a `PATCH` request to enable the subscription when your handler is ready to process incoming requests.

    [**PATCH** /webhooks/subscriptions/\{subscriptionId}](/api-reference/webhooks/update-webhook-subscription)

    ```json Request theme={null}
    {
      "enabled": true
    }
    ```
  </Step>
</Steps>