Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Webhook Subscriptions

  • List webhook event types

  • List webhook subscriptions

  • Create webhook subscription

  • Delete webhook subscription

  • Retrieve webhook subscription

  • Update webhook subscription

  • Update webhook subscription signature key

  • Test webhook subscription

<- Webhook Subscriptions API

Webhook Subscriptions API

All versions ->

Create webhook subscription

POST

 /v2/webhooks/subscriptions

Creates a webhook subscription.

Try in API Explorer
Link to section

Request body

Example code

Link to section

idempotency_key

string

A unique string that identifies the CreateWebhookSubscription request.

Max Length
45
Link to section

subscription

Required

The Subscription to create.

Link to section

Response fields

Link to section

errors

Information on errors encountered during the request.

Link to section

subscription

The new Subscription.

Link to section

Examples

All versions ->

POST /v2/webhooks/subscriptions
curl https://connect.squareup.com/v2/webhooks/subscriptions \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "idempotency_key": "63f84c6c-2200-4c99-846c-2670a1311fbf", "subscription": { "name": "Example Webhook Subscription", "event_types": [ "payment.created", "payment.updated" ], "notification_url": "https://example-webhook-url.com", "api_version": "2021-12-15" } }'

Response JSON

{ "subscription": { "id": "wbhk_b35f6b3145074cf9ad513610786c19d5", "name": "Example Webhook Subscription", "enabled": true, "event_types": [ "payment.created", "payment.updated" ], "notification_url": "https://example-webhook-url.com", "api_version": "2021-12-15", "signature_key": "1k9bIJKCeTmSQwyagtNRLg", "created_at": "2022-01-10 23:29:48 +0000 UTC", "updated_at": "2022-01-10 23:29:48 +0000 UTC" } }