Use Webhooks to Receive Catalog Notifications

Applies to: Catalog API

Learn how to use a webhook to build reminders to update your catalog.

The Catalog API supports the following webhook:

Use the catalog.version.updated webhook to build real-time notifications that help you keep your catalog in sync.

The catalog.version.updated webhook sends an update when the seller's catalog is updated in any way. You can use this webhook as a notification to tell you when it's time to sync your catalog.

To subscribe to notifications of catalog.version.updated events, you can configure webhooks for your application. A webhook registers the URL that Square should send notifications to, the events you want to be notified about, and the Square API version.

To configure a webhook

1. In the Developer Console, open the application to which you want to subscribe.

2. In the left pane, choose Webhooks.

3. At the top of the page, choose Sandbox or Production. Choose Sandbox for testing.

4. Choose Add Endpoint, and then configure the endpoint:

   1. For Webhook Name, enter a name such as Catalog Webhook.
   2. For URL, enter your notification URL. If you don't have a working URL yet, you can enter https://example.com as a placeholder. You can also sign on to webhook.site to obtain a test URL for webhook event notifications and use the obtained test URL here.
   3. Optional. For API Version, choose a Square API version. By default, this is set to the same version as the application.
   4. For Events, choose catalog.version.updated. If you want to receive notifications about other events at the same webhook URL, choose them or configure another endpoint.
   5. Choose Save.

   Note

   In the production environment, ignore the Enable Webhooks setting on the Webhooks page. This setting applies to webhooks for Connect V1 APIs (deprecated).

For more information about webhooks, see Square Webhooks.

This webhook sends a notification any time any catalog object is created, updated, or deleted.

For catalog.version.updated notifications, the data field includes a timestamp indicating when the catalog was last updated.

{
  "type": "catalog.version.updated",
  "event_id": <UUID-for-the-event>,
  "created_at": "2019-05-14T17:51:44Z",
  "merchant_id": "MERCHANT123",
  "data": {
    "type": "catalog_version",
    "id": "<UUID-for-the-data>",
    "object": {
      "catalog_version": {
        "updated_at": "2019-05-14T17:51:27Z"
      }
    }
  }
}

You don't need to use the updated_at timestamp from the webhook in the recommended sync flow. It's provided for convenience, but the value you pass to SearchCatalogObjects is the timestamp of the last time you synced.

When you receive a catalog.version.updated notification, call the SearchCatalogObjects endpoint and set the begin_time field to the timestamp of the last time you synced your catalog. This retrieves all the CatalogObjects updated after the timestamp listed in begin_time.

You should store the latest_time value returned by the SearchCatalogObjects endpoint, so you can use it in your next call to SearchCatalogObjects. Using a locally generated timestamp might cause you to miss updates as a result of time skew between the Square server and your application.

A sample call to SearchCatalogObjects is as follows:

To include catalog objects that have been deleted since BEGIN_TIME in the search results: add "include_deleted_objects":true to the bodyParameters: