v2 Webhooks

What It Does

Set up real-time notifications for updates to product inventories.

Backend

Square Webhooks are HTTP calls or snippets of code that are triggered by specific events. To detect changes to data, typical APIs would require calls at regular time intervals. Square Webhooks 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 Webhooks to update the offline inventory table with inventory quantity updates from Square webhook notifications.

Requirements and limitations
Permalink Get a link to this section

  • v2 Webhook support is currently limited to the Connect v2 Catalog and Inventory APIs.

Product components
Permalink Get a link to this section

A Square Webhook integration includes the following:

  • Events — An action or change in data that generates notifications. Square Webhooks 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.

Subscriptions
Permalink Get a link to this section

Developers create v2 Webhook subscriptions in the Webhooks setting page of their Square application. A single v2 Webhook subscription can subscribe to all available v2 webhooks 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 Application Dashboard. When events occur, Square Webhooks 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

Webhook 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 webhook 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.