Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
v2 Webhooks

What It Does

Set up real-time notifications for updates to Square account data.


Square v2 Webhooks (beta) are subscriptions to events that updated data in a Square account. Webhooks POST data state updates on specific events. To detect changes to data, typical APIs would require calls at regular time intervals. Square v2 Webhooks (beta) replace regular API calls with instant, real-time notifications.

For example, consider a company that keeps an offline product catalog with details about items and inventory levels. This company can use Square v2 Webhooks (beta) to update the offline inventory table with inventory quantity updates from webhook notifications.

Requirements and limitations
Permalink Get a link to this section

  • v2 Webhooks (beta) support is currently limited to the Catalog, Inventory, Payments, Refunds, Disputes, and Labor APIs.

Product components
Permalink Get a link to this section

A Square v2 Webhooks (beta) integration includes the following:

  • Events — An action or change in data that generates notifications. Square v2 Webhooks (beta) can be used to create alerts that trigger for these events.

  • Subscriptions — Configured in the developer portal to subscribe to notifications associated with a specific event.

  • Notification URL — The configurable service in the application to which alerts are sent.

  • Notification body — Details about the event that generated the alert, such as the time it happened or an ID identifying the data that changed.

Permalink Get a link to this section

Developers create v2 Webhooks (beta) subscriptions in the Webhooks setting page of their Square application. A single v2 Webhook subscription can subscribe to all available v2 Webhooks (beta) for all authorized accounts.

A subscription configuration includes:

  • a notification URL of the webhook endpoint.

  • the Connect v2 API version of the event notification.

  • a list of events to listen for.

Notification URL
Permalink Get a link to this section

Applications need at least 1 reachable notification URL to receive and process webhook events from Square. Notification URLs are set in the Webhooks page of your application in the Application Dashboard. When events occur, Square v2 Webhooks (beta) sends a POST request with event data to each notification URL that is set to listen for the event type.

Batch operations
Permalink Get a link to this section

A batch operation is a single webhook notification that includes an array of objects with field values relevant to each operation in a batch. A batch operation notification is homogeneous. That is, each operation in the batch is always of the same type.

For example, a batch of counts is updated, 1 webhook notification is sent for the batch. The batch notification includes an array of objects that represent individual counts. During and after a bulk operation such as an import, webhook notifications are sent in batches of 100 counts.

Idempotency support
Permalink Get a link to this section

v2 Webhooks (beta) events for Connect v2 support idempotency by including an event_id field in the body of a notification request. This UUID value lets a webhook listener bypass notification processing on a webhook notification that is sent more than once.

    "merchant_id": "6VEKB6X1E99V8",
    "type": "webhooks.test_notification",
    "event_id": "4da4f446-01d2-4747-4fd5-7b7b1995df85",
    "created_at": "2019-06-07T17:23:48.562168136Z",
    "data": {
        "type": "webhooks",
        "id": "93b34df4-3343-4cdd-b9b5-8a7f63e41707"

Actionable events
Permalink Get a link to this section

The body of a v2 Webhooks (beta) event provides the ID of the resource whose state is changed by the event. The webhook listener can use Connect v2 API requests to retrieve the associated resource from Square and update local resources as needed. For example, an inventory count notification returns the location ID, catalog object ID, and variation of any item whose stock level has changed.

   "data": {
      "inventory_counts": [
           "location_id": "locationToken",
           "catalog_object_id": "XYZ456",
           "catalog_object_type": "ITEM_VARIATION",
           "state": "IN_STOCK",
           "quantity": "12.375",
           "calculated_at": "2019-05-14T17:51:27Z"

Get started

Use the guides below to subscribe to Webhook events.