---
url: https://docs.youcan.shop/youcan-pay/webhooks/create.md
---
# Create a Webhook

Registers a new webhook on the current authenticated account.

**Required scope (OAuth only):** `create-webhook`

An account may have at most **5** webhooks. Creating a sixth returns `422`.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `url` | string required | The HTTPS URL notifications are delivered to. Maximum 255 characters. |
| `enabled_events` | array required | The events to subscribe to. At least one, each one of `transaction.paid`, `transaction.failed`, `transaction.refunded`, `withdrawal.created`. |

## Returns

Returns the created [Webhook object](/youcan-pay/webhooks/object) with `201`.

## Request

**Endpoint:** `https://youcanpay.com/api/v2/webhooks`
**Method:** `POST`

```bash
$ curl --location -g --request POST 'https://youcanpay.com/api/v2/webhooks' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  -u 'YOUR_PRIVATE_KEY:' \
  --data '{
    "url": "https://example.com/webhooks/youcan-pay",
    "enabled_events": ["transaction.paid", "transaction.refunded"]
  }'
```

## Response

```json
{
  "object": "v2.webhook",
  "id": "9b1f2c34-5d6e-4a7b-8c9d-0e1f2a3b4c5d",
  "url": "https://example.com/webhooks/youcan-pay",
  "is_live_mode": true,
  "enabled_events": "[\"transaction.paid\",\"transaction.refunded\"]",
  "created_at": "2026-09-09 11:04:22"
}
```

## Errors

| Status | Description |
| --- | --- |
| `422` | The URL is missing or not a valid URL, `enabled_events` is empty or contains an unknown event, or the account already has 5 webhooks. |