Keep Your External Catalog Synced

Applies to: Catalog API

Learn how to use a webhook to accept notifications to sync your offline catalog.

The Catalog API supports the following webhook:

Use the catalog.version.updated webhook to build real-time notifications that help you keep the seller's item library in sync with your external catalog. If you're using your catalog to render, for example, a restaurant menu or an online catalog, responding immediately to item library updates is important.

The version of a seller's catalog increments whenever a catalog object is mutated (created, updated, or deleted). The mutated object gets the new version number, while unmutated objects keep any of the previous version numbers. The webhook body includes a timestamp for when a new catalog version number is generated, which corresponds to the time when an object mutation is made. You can use this webhook to notify you when it's time to sync your catalog.

There's no need to refetch a seller's entire item library when you sync it with your catalog. Use the webhook notification to retrieve only the catalog objects that were mutated since the last time your endpoint received this webhook notification.

Catalog objects can be mutated by the Square Dashboard, Square Point of Sale, or Catalog API integrations such as the one that you're developing. The catalog.version.updated webhook notifies your application of mutations generated in an item library regardless of what triggered the change. This means you get mutation notifications for events that your application didn't originate. Your webhook POST endpoint might be busy but it captures all mutations, regardless of the origin. This is a critical advantage if you need to keep your external catalog synced in real time.

For example, if a seller updates the description of each cheese variation they sell, saving an edited variation increments the catalog version and triggers a webhook notification. In another common example, a seller imports an entire item library from a single source file. In this case, each imported item triggers a webhook notification rather than a single notification for the whole import.

You can handle each notification and call SearchCatalogObjects to retrieve the mutated object or handle a notification every minute to get all objects mutated since the previous handled notification.

Object mutations from Catalog API upsert and batch upsert requests also trigger webhook notifications. For a batch upsert, a single notification is sent for the entire batch, regardless of its size.

To subscribe to notifications of catalog.version.updated events, you need to configure webhooks for your application. A webhook registers the POST endpoint 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 that you want to receive webhook events.

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. Webhook Name - Enter a name such as Catalog Webhook.
   2. URL - Enter your notification URL. If you don't have a working POST endpoint yet, you can enter https://example.com as a placeholder. You can also sign in to webhook.site to obtain a test URL for webhook event notifications and use the obtained test URL.
   3. API Version - Choose a Square API version. By default, this is set to the same version as your application. The API version sets the webhook event body to the Square API version that you use in your application.
   4. 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, which are now Retired.

For more information, see Square Webhooks.

The catalog.version.updated 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 potential time discrepancies 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.