Square Webhooks

Feature Overview

Use the features of Square Webhooks to set up real-time notifications.

Square Webhooks are subscriptions to events that updated data in a Square account. Events can be generated by Square API operations and by Square apps such as the Square Point of Sale app. A webhook subscription instructs Square to send a notification via POST whenever the state of Square account data changes.

Before Square Webhooks were released, an app would detect a state change by polling the relevant endpoint at regular timed intervals. Square Webhooks replace polling with instant, real-time pushed notifications.

For example, consider a company that keeps an off-line product catalog with details about items and inventory levels. This company can use Square Webhooks to keep the off-line inventory table in sync with Square by processing webhook notifications for each event that changes the level of an inventory item or catalog description.

Webhook components
Permalink Get a link to this section

A Square Webhooks integration includes the following:

  • Events. An action or change in data that generates notifications. Webhooks can be used to create alerts that trigger for these events. For a list of supported APIs, see Webhook 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 webhook subscriptions in the Webhooks setting page of their Square application. A single Square Webhook subscription can include all available webhook events for all authorized accounts.

A subscription configuration includes:

  • A notification URL of the webhook endpoint.

  • The Square 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 one 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 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, one 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

Webhooks events for Square API 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 Webhooks event provides the ID of the resource whose state is changed by the event. The webhook listener can use Square 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"
        },
      ]
   }

Requirements and limitations
Permalink Get a link to this section

App webhook notification endpoints require HTTPS.

Get started

Use the guides below to subscribe to Webhook events.