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.