New Webhook Event for Syncing with Square Catalog

We’re excited to share the new and improved webhook event for updates to Square Catalog, called CatalogVersionUpdated. CatalogVersionUpdated is a new webhook event available that helps developers stay in sync with a seller’s catalog and better maintain their omnichannel integrations.

In talking with developers, we heard consistent themes of how we could improve the sync experience for Square Catalog:

• “I need to keep pace with Square’s catalog to maintain trust with my customers.”
• “I need to easily catch up with events that occurred while my service was offline.”
• “I need more efficiency because building our own polling infrastructure is a painstaking process to support and maintain.”
• “I need notifications that are reliable.”

These themes are the foundation of our new webhook event: CatalogVersionUpdated. A webhook that is triggered anytime any catalog object is created, updated, or deleted.

Let’s dive into an example:

The body of this webhook includes the timestamp at which the catalog was last updated:

{
  "type": "catalog.version.updated",
  "event_id": UUID,
  "created_at": "2019-05-14T17:51:44Z",
  "merchant_id": "merchantToken",
  "data": {
    "catalog_version": {
      "updated_at": "2019-05-14T17:51:27Z"
    }
  }
}

Update your catalog

When you receive a CatalogVersionUpdated notification, we recommend calling SearchCatalogObjects and setting begin_time to the value of latest_time that was returned in the response the last time you called SearchCatalogObjects. We recommend storing the latest_time value and using it in your next call to SearchCatalogObjects rather than using a locally generated timestamp. This will prevent missing updates as a result of race conditions or time skew between your server and ours, as this will return all CatalogObjects that have been updated since the last time you checked.

// POST /v2/catalog/search
{
  “begin_time”: "2019-05-13T18:00:00Z"
}

If you currently poll SearchCatalogObjects for changes at regular intervals, you can instead use the webhook as a notification that it’s time to sync because the webhook event sends an update when the catalog for an application is updated in any way at all. It’s not a bad idea to continue to poll as a backup mechanism, but you can consider increasing the interval length.

You can subscribe to webhooks from any of your applications by opening the application details in your Developer Dashboard. To learn more, check out our Subscribe to Webhook Events and Catalog API webhooks user guide.