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

Subscribe to Events

Subscribe to Square Connect v2 Webhooks.

Backend

v2 Webhooks provides a client-level subscription model that allows an application to receive event notification types for all authorized merchants with 1 or more subscriptions.

An app that provides Connect v2 webhook notification processesing for multiple Square accounts may use a single v2 Webhook subscription to service all accounts. This can reduce the amount of onboarding work that a developer needs to do when bringing a new Square account online.

Webhook events
Permalink Get a link to this section

The following webhook events are available for v2 Webhooks:

WebhookDescription
inventory.count.updatedThe quantity was updated for a catalog item variation.
Webhook notification data is packaged as: InventoryCount[]
catalog.version.updatedThe catalog was updated.
Webhook notification data is packaged as:
"catalog_version": { "updated_at": "2019-05-14T17:51:27Z"}.
labor.shift.createdA worker started a shift.
Webhook notification data is packaged as a Shift
labor.shift.updatedA Shift was updated. Typically a break was started, ended, or a worker ended the shift.
Webhook notification data is packaged as a Shift
labor.shift.deletedA Shift was deleted.
Notification data includes the deleted Shift ID and isDeleted flag.

Subscribe to a webhook
Permalink Get a link to this section

Each webhook endpoint creates a single event subscription for event types for a specified Connect v2 API version.

An application needs just one subscription per notification endpoint that it configures. That endpoint can handle all event types or any sub-set that the developer chooses. Use the Developer Dashboard Webhooks page to add as many webhooks as needed.

A webhook is configured with a notification URL, API version, and event type. This allows a developer to assign a notification endpoint to handle webhook events based on any combination of these properties. The API version is defaulted to the version pinned to the application registration but can be set to other versions.

Important

The notification URL must be formatted correctly, use the HTTPS protocol, and be reachable. Otherwise, the error message "Your webhook for webhook was not created. URL is not valid" is displayed when you click Save.

Webhookv2subscription

Test the subscription
Permalink Get a link to this section

Once you have created a webhook endpoint and configured the subscription, you can quickly test your end point to see if it will handle the notification request correctly. To do this:

  1. Click on the webook event you want to test. A Webhook Details dialog opens.

  2. Click More on the bottom of the dialog to open a context menu.

  3. Click Send Test Event to send an event to the event listener that you set up at the endpoint.


The webhook notification body includes a merchant ID, event type, event ID, a creation timestamp, and an empty data field. Use this test to verify that your Validate Notifications logic is working.

Next steps

Now that you are subscribed to events, add code to validate webhook notifications.