In the sandbox environment, when receiving the catalog.version.updated webhook callback, my id is empty, and I can't tell which object type was changed

Hi there. I’ve recently been testing the webhook callback feature in the sandbox environment, and I am able to receive the callbacks.

The content I receive looks like this:

json

{
“merchant_id” : “MLVVMHNB69GR3”,
“type” : “catalog.version.updated”,
“event_id” : “59a8d878-0fe3-310c-8610-1f7e5dde659d”,
“created_at” : “2026-11-18T10:02:34.252927974Z”,
“data” : {
“type” : “catalog_version”,
“id” : “”,
“object” : {
“catalog_version” : {
“updated_at” : “2026-11-18T10:02:32.098Z”
}
}
}
}
My first question is: why is the id I receive empty? And I have no way of telling which CatalogObject type was changed — this payload doesn’t contain any of the actual modification content.

My second question is: if the id were not empty, or if I knew the type (item, image, category), would I still have to query Square for the specific data using that id and then update my local data accordingly?

Sandbox Application ID
sandbox-sq0idb-KA6cqEi3t4onjaIVvOIFAg

I think I’ve figured it out — these types (item, image, CATEGORY) each correspond to a different id on the CatalogObject.

Could you tell me which API/endpoint I should use to query a CatalogObject by its id? I looked at /v2/catalog/info and /v2/catalog/list, but neither of them seems to have an id parameter in the request.

The payload is expected. catalog.version.updated is a catalog-level event, so it only carries the new catalog_version.updated_at timestamp. It doesn’t include an object ID, object type, or any details of what changed, so the empty id is normal and not a Sandbox issue.

To answer your second question: yes, you need to call Square to get the changes. Webhooks only tell you that the catalog changed. The recommended pattern:

  • Store the updated_at from each event.
  • On the next event, call SearchCatalogObjects with begin_time set to the previously stored timestamp. You’ll get back only the objects that changed since then, including deleted ones if you set include_deleted_objects: true.
  • Set object_types to the types you care about (e.g. ITEM, ITEM_VARIATION, CATEGORY, IMAGE). The type on each returned object tells you what changed.
  • Don’t call ListCatalog on every event. It returns the whole catalog and you’ll hit rate limits faster. Deduplicate events by event_id.

The above should return the info of all of catalog objects you need. Followup batch retrieve catalog objects shouldn’t be needed.