Webhook Subscriptions API

Applies to: Webhook Subscriptions API | Events API | Square Webhooks

Learn about the Webhook Subscriptions API, which you can use to programmatically subscribe to webhooks.

Link to section


Using the Developer Dashboard to manually update webhook subscriptions can become complex when you have to update numerous applications for new event types or functionality.

The Webhook Subscriptions API lets you programmatically manage your webhook subscriptions, including creating, updating, and deleting webhook subscriptions associated with an event.

With the Webhook Subscriptions API, you can:

  • Subscribe to receive notifications of events you want to know about. To subscribe, you need to register a notification URL, which Square sends notifications to when events occur.
  • Retrieve all event types that an application can subscribe to.
  • List all subscriptions for an application.
  • Trigger a test notification to the subscription's notification URL.


Because webhook subscriptions are owned by the application and not by any one seller, you cannot use OAuth access tokens with the Webhook Subscriptions API. You must use the application's personal access token.

The Events API is a pull-based alternative to webhook subscriptions. In addition to receiving real-time event notifications, you can periodically poll the Events API to retrieve events.

Link to section

Example use cases

With the Webhook Subscriptions API, you can integrate webhook subscriptions into CI/CD (Continuous Integration/Continuous Delivery) pipelines. For example, you can rotate the signature key used to sign webhooks, configure webhooks while bootstrapping applications and test environments, and update webhooks for new event types or API versions.

Link to section

Rotating the signature key

Consider a scenario where you want to rotate the signature key every 90 days. You can call UpdateWebhookSubscriptionSignatureKey to get a new key that you can use to validate all future webhooks with.

curl https://connect.squareup.com/v2/webhooks/subscriptions/wbhk_b35f6b3145074cf9ad513610786c19d5/signature-key \ -X POST \ -H 'Square-Version: 2022-08-17' \ -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "idempotency_key": "ed80ae6b-0654-473b-bbab-a39aee89a60d" }'

The following is an example response:

{ "signature_key": "mAskrnZb__o9fdCO42C8zg" }
Link to section

Configure webhooks for an application from scratch

The following steps show how to configure webhooks for an application from scratch:

  1. Check whether the application has existing subscriptions with the ListWebhookSubscriptions endpoint.

    curl https://connect.squareup.com/v2/webhooks/subscriptions \ -H 'Square-Version: 2022-08-17' \ -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \ -H 'Content-Type: application/json'

    The following is an example response for an application with no existing subscriptions:

  2. Use the ListWebhookEventTypes endpoint to see all the event types that you can subscribe to.

    curl https://connect.squareup.com/v2/webhooks/event-types \ -H 'Square-Version: 2022-08-17' \ -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \ -H 'Content-Type: application/json'

    The following is an example response:

  3. Use the CreateWebhookSubscription endpoint to add your notification URL and list of events that you want to subscribe to.

    The following is an example response:

  4. To validate the notification URL, use the TestWebhookSubscription endpoint.

    curl https://connect.squareup.com/v2/webhooks/subscriptions/wbhk_b35f6b3145074cf9ad513610786c19d5/test \ -X POST \ -H 'Square-Version: 2022-08-17' \ -H 'Authorization: Bearer PERSONAL_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "event_type": "payment.created" }'

    The following is an example response:

    { "subscription_test_result": { "id": "23eed5a9-2b12-403e-b212-7e2889aea0f6", "status_code": 404, "payload": " {\"merchant_id\":\"1ZYMKZY1YFGBW\",\"type\":\"payment.created\",\"event_id\":\"23e ed5a9-2b12-403e-b212-7e2889aea0f6\",\"created_at\":\"2022-01- 11T00:06:48.322945116Z\",\"data\":{\"type\":\"payment\",\"id\":\"KkAkhdMsgzn59SM8A89WgKwekxLZY\",\"object\":{\"payment\":{\"amount_money\":{\"amount\":100,\"currency\":\"USD\"},\"approved_money\":{\"amount\":100,\"currency\":\"USD\"},\"capabilities\":[\"EDIT_TIP_AMOUNT\",\"EDIT_TIP_AMOUNT_UP\",\"EDIT_TIP_AMOUNT_DOWN\"],\"card_details\":{\"avs_status\":\"AVS_ACCEPTED\",\"card\":{\"bin\":\"540988\",\"card_brand\":\"MASTERCARD\",\"card_type\":\"CREDIT\",\"exp_month\":11,\"exp_year\":2022,\"fingerprint\":\"sq-1-Tvruf3vPQxlvI6n0IcKYfBukrcv6IqWr8UyBdViWXU2yzGn5VMJvrsHMKpINMhPmVg\",\"last_4\":\"9029\",\"prepaid_type\":\"NOT_PREPAID\"},\"card_payment_timeline\":{\"authorized_at\":\"2020-11-22T21:16:51.198Z\"},\"cvv_status\":\"CVV_ACCEPTED\",\"entry_method\":\"KEYED\",\"statement_description\":\"SQ *DEFAULT TEST ACCOUNT\",\"status\":\"AUTHORIZED\"},\"created_at\":\"2020-11-22T21:16:51.086Z\",\"delay_action\":\"CANCEL\",\"delay_duration\":\"PT168H\",\"delayed_until\":\"2020-11-29T21:16:51.086Z\",\"id\":\"hYy9pRFVxpDsO1FB05SunFWUe9JZY\",\"location_id\":\"S8GWD5R9QB376\",\"order_id\":\"03O3USaPaAaFnI6kkwB1JxGgBsUZY\",\"receipt_number\":\"hYy9\",\"risk_evaluation\":{\"created_at\":\"2020-11-22T21:16:51.198Z\",\"risk_level\":\"NORMAL\"},\"source_type\":\"CARD\",\"status\":\"APPROVED\",\"total_money\":{\"amount\":100,\"currency\":\"USD\"},\"updated_at\":\"2020-11-22T21:16:51.198Z\",\"version_token\":\"FfQhQJf9r3VSQIgyWBk1oqhIwiznLwVwJbVVA0bdyEv6o\"}}}}", "created_at": "2022-08-17 00:06:48.322945116 +0000 UTC m=+3863.054453746", "updated_at": "2022-08-17 00:06:48.322945116 +0000 UTC m=+3863.054453746" } }
Link to section

Update a webhook subscription

Webhook subscriptions are versioned independent of the default version of your application. The version of a webhook subscription determines the version of the event that's sent to the webhook.

Imagine you want the new event types or data object fields added in subsequent releases to show up in your webhooks. You can use the UpdateWebhookSubscription endpoint to change the api_version field to the newer version and add the newer event_types that you want to get notified for. You can also edit the subscription name or notification_url, as well as enable or disable the subscription.

The following is an example response:

Link to section

See also