Catalog API

Webhooks

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

Backend
Catalog API

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

Did you know?

If you regularly poll SearchCatalogObjects for updates, you can use this webhook and then increase the length of time between your polls.

Subscribe to catalog.version.updated
Permalink Get a link to this section

You can subscribe to webhooks from any of your applications by opening the application details in your Developer Dashboard. Learn more from our Subscribe to Webhook Events guide.

How catalog.version.updated works
Permalink Get a link to this section

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,
  "created_at": "2019-05-14T17:51:44Z",
  "merchant_id": "MERCHANT123",
  "data": {
    "catalog_version": {
      "updated_at": "2019-05-14T17:51:27Z"
    }
  }
}

You do not 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 will retrieve all CatalogObjects updated after the timestamp listed in begin_time.

We strongly recommend storing 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 may cause you to miss updates as a result of race conditions or time skew between the Square server and your application.

A sample call to SearchCatalogObjects:

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer SELLER_ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
  "begin_time": "BEGIN_TIME"
}' \
'https://connect.squareup.com/v2/catalog/search'