Skip to content
API Docs

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_event ignores subscriptions; it's always delivered when fired manually.

Echo-suppression

Don't expect to receive your own writes back

Your own API calls are answered by their responses, not by events. Creating an order or upserting a customer sends nothing to your URL. A watch or part that sells through an order you reported does not come back as 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

For any 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

A spare part is not a listing: it has a quantity and no watch. Part events therefore live under 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

{
  "id": "24f0ebb1-73d7-4e99-9901-821078594271",
  "object": "listing"
}

listing.updated

Fires when a published listing's data changes (price, photos, watch attributes, ...).

data.object

{
  "id": "24f0ebb1-73d7-4e99-9901-821078594271",
  "object": "listing"
}

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

{
  "id": "24f0ebb1-73d7-4e99-9901-821078594271",
  "object": "listing"
}

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

{
  "id": "24f0ebb1-73d7-4e99-9901-821078594271",
  "object": "listing",
  "status": "sold"
}

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

{
  "id": "24f0ebb1-73d7-4e99-9901-821078594271",
  "object": "listing",
  "status": "published"
}

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

{
  "id": "9c2f0a71-5d18-4a5e-9b64-0f1c2e3d4a5b",
  "object": "part"
}

part.updated

Fires when a part already on the channel changes (price, quantity, photos, compatibility, ...).

data.object

{
  "id": "9c2f0a71-5d18-4a5e-9b64-0f1c2e3d4a5b",
  "object": "part"
}

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

{
  "id": "9c2f0a71-5d18-4a5e-9b64-0f1c2e3d4a5b",
  "object": "part"
}

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

{
  "id": "9c2f0a71-5d18-4a5e-9b64-0f1c2e3d4a5b",
  "object": "part",
  "status": "sold_out"
}

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

{
  "id": "9c2f0a71-5d18-4a5e-9b64-0f1c2e3d4a5b",
  "object": "part",
  "quantity": 3
}

Order events

order.fulfilled

Fires when an order is matched to a listing and the dealer marks it fulfilled.

data.object

{
  "id": "d7df4fbe-2c0c-4328-a3b0-a32c68cabd43",
  "object": "order",
  "external_id": "shop-12345",
  "status": "matched",
  "total_amount": 1500000,
  "currency": "USD",
  "buyer": { "name": "Alice", "email": "alice@example.com", "country": "US" },
  "line_items": [{ "sku": "116610LN", "quantity": 1, "unit_amount": 1500000 }],
  "ordered_at": "2026-05-08T08:41:16.345+00:00",
  "created_at": "2026-05-08T08:41:16.770507+00:00"
}

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

{
  "id": "d7df4fbe-2c0c-4328-a3b0-a32c68cabd43",
  "object": "order",
  "external_id": "shop-12345",
  "status": "dismissed",
  "total_amount": 1500000,
  "currency": "USD",
  "buyer": { "name": "Alice", "email": "alice@example.com", "country": "US" },
  "line_items": [{ "sku": "116610LN", "quantity": 1, "unit_amount": 1500000 }],
  "ordered_at": "2026-05-08T08:41:16.345+00:00",
  "created_at": "2026-05-08T08:41:16.770507+00:00"
}

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

{
  "message": "Test event from /v1/test/webhook_ping."
}