Event catalog
Every webhook event the integration emits, what it means, and the shape of data.object. The envelope wrapping each payload is documented on the Webhooks page.
Subscribing to events
Subscriptions are managed from Custom Integration → Settings → Event subscriptions. The default is the wildcard *: your endpoint receives every event.
- Tick individual events to allowlist them.
- Wildcard a namespace with e.g.
listing.*(subscribe to all listing events). integration.test_eventignores subscriptions; it's always delivered when fired manually.
Echo-suppression
Don't expect to receive your own writes back
listing.sold, listing.updated, part.sold_out or part.in_stock when every line of that order that sold it named it by your SKU. A watch or part the dealer links by hand to a line that did not name it is news to you, and is announced like any other sale. This is what stops trivial event-loops between your custom site and WatchTraderHub.Cancelling an order through POST /v1/orders/{id}/cancel sends no order.cancelled, but it puts the order's watches and parts back in stock, and that is announced like any other restock: listing.in_stock for every watch put back on your channel, with the status the watch went back to, which WatchTraderHub decides (a watch can come back reserved or as a draft); a watch with several pieces that is still for sale gets listing.updated as well; and part.in_stock with the part's new quantity.
Events triggered elsewhere (other integrations like Shopify or eBay, actions taken in the dashboard) still fire to your URL as normal.
Events
Listing events carry the id, not the watch
listing.* event, data.object carries the listing id and object: "listing", not the watch itself. listing.sold also carries status: "sold", and listing.in_stock the status the listing went back to. To get the watch (brand, model, price, photos, caliber, complications, water resistance, power reserve), fetch GET /v1/listings/{id} when the event arrives. A permanent deletion sends listing.unpublished with deleted: true. Do not fetch that listing because it has already been removed and the API will return 404. Order events are the exception: they include the full order inline, exactly as GET /v1/orders/{id} returns it.Spare parts are a separate namespace
part.*, and a subscription to listing.* does not receive them. Fetch GET /v1/parts/{id} when one arrives, except for part.unpublished, where the part is already off the channel and the API will return 404.Listing events
listing.published
Fires when the dealer toggles an inventory item ON for the custom channel.
data.object
listing.updated
Fires when a published listing's data changes (price, photos, watch attributes, ...).
data.object
data.previous_attributes: Reserved: currently always an empty object. Fetch the listing to read its current values.
listing.unpublished
Fires when the dealer toggles a listing OFF for the custom channel.
data.object
listing.sold
Fires when a listing transitions to sold (either manually or via order matching). Not sent for a watch that sells through an order you reported when every line that sold it named it by your SKU.
data.object
listing.in_stock
Fires when a watch is put back in stock on your custom channel: a sale of it is cancelled, deleted or fully returned, or the import that sold it is undone. `status` is the status it went back to, which is not always published: a watch can come back reserved or as a draft. A watch with several pieces that was still for sale gets it too when the sale of one piece is cancelled, deleted or returned, together with listing.updated.
data.object
Spare part events
part.published
Fires when the dealer puts a spare part ON the custom channel. Fetch GET /v1/parts/{id} for the part.
data.object
part.updated
Fires when a part already on the channel changes (price, quantity, photos, compatibility, ...).
data.object
part.unpublished
Fires when the dealer takes a spare part OFF the custom channel. The part stops being readable once this arrives, so do not fetch it.
data.object
part.sold_out
Fires when a part reaches zero units, whether it was sold in WatchTraderHub or through an order from another channel. Not sent for a part that sells out through an order you reported when every line that sold it named it by your SKU. The part stays readable and its status reads sold_out.
data.object
part.in_stock
Fires when a live part's stock count changes and it still has units: a restock, a return, a cancelled sale, a fit, or a partial sale. The new count is in quantity.
data.object
Order events
order.fulfilled
Fires when an order is matched to a listing and the dealer marks it fulfilled.
data.object
order.cancelled
Fires when the dealer dismisses one of your orders in WatchTraderHub. Not sent for a cancel you made yourself through `POST /v1/orders/{id}/cancel`: the response already tells you.
data.object
data.previous_attributes: Reserved: currently always an empty object. The order payload carries the new status.
Integration events
integration.test_event
Fires from `POST /v1/test/webhook_ping`. Always delivered regardless of `subscribed_events` filtering.
data.object
