Create a Webhook Endpoint

​

Creates a Webhook Endpoint for the exact event identifiers in enabled_events. Wildcard subscriptions are not accepted.

Set api_version to v1 or v2 to choose the event payload schema. If omitted, it defaults to v1. The payload version cannot be changed after creation.

Set connect to true to also receive selected events from accounts connected to your platform account. If omitted, it defaults to false.

You can also create, test, and manage webhook endpoints in the Merchant Dashboard. The dashboard provides a user interface for registering endpoints and choosing events.

Related guides: Webhook Event Catalogue and Webhook Signature Verification

Body·

required
application/json

Parameters for creating a Webhook Endpoint.

  • name
    Type: string
    max length:  
    5000
    required

    Name to help identify the webhook.

  • url
    Type: string
    max length:  
    5000
    required

    The URL of the webhook endpoint.

  • enabled_events
    Type: enum
    required

    Exact event identifiers this endpoint receives. Wildcards are not accepted.

  • api_version
    Type: enum

    Payload schema version used for event delivery. If omitted, Paypercut uses v1.

    values
    • v1

      Legacy Checkout Session and Payment Intent payload shapes. Used when api_version is omitted for backward compatibility.

    • v2

      Recommended for new integrations. Uses the current Checkout Session and Payment Intent resource shapes.

  • connect
    Type: boolean

    Whether the endpoint also receives selected events from accounts connected to the platform account. If omitted, Paypercut uses false.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/webhooks
curl https://api.paypercut.io/v1/webhooks \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Production payment events",
  "url": "https://example.com/webhooks/paypercut",
  "api_version": "v2",
  "connect": true,
  "enabled_events": [
    "checkout_session.completed",
    "payment_intent.authorized",
    "payment_intent.captured",
    "invoice.paid",
    "invoice.payment_failed"
  ]
}'

{
  "id": "string",
  "created": "2026-10-02T06:37:26.636Z",
  "name": "string",
  "url": "https://example.com/webhooks/paypercut",
  "status": "active",
  "api_version": "v2",
  "connect": true,
  "enabled_events": [
    "checkout_session.completed",
    "payment_intent.authorized",
    "payment_intent.captured",
    "payment.succeeded",
    "payment.failed",
    "invoice.paid",
    "invoice.payment_failed"
  ],
  "secret": "string"
}

Successful response.