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 with 201.

Request

Endpoint: https://youcanpay.com/api/v2/webhooksMethod: POST

$ 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

{
  "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.