Quickstart

Generate a key, set a webhook URL, send a test event, pull your first listings. About ten minutes if nothing goes sideways. The flow assumes you already have a WatchTraderHub dealer account on the Business tier or higher.

Prerequisites

• A dealer account at /channels/custom.
• A webhook receiver URL, for testing, use webhook.site or any HTTPS endpoint that returns 200.
• cURL (or any HTTP client). Examples below use cURL.

1. Generate an API key

From the dealer dashboard, open Sales Channels → Custom Integration. The first time you visit this page you'll see a four-step wizard. Click Generate API key. The key is shown exactly once in a modal. Copy it now.

2. Set your webhook URL

Paste your receiver URL into the Webhook URL field and click Save. A second modal reveals your whsec_… signing secret. Copy and store it the same way you stored the API key, it's also a one-shot reveal. You'll need it to verify incoming deliveries.

3. Activate the integration

Flip Integration enabled on. The status badge changes from DISABLED to TEST MODE. Test mode is on by default so nothing you create during setup pollutes your live dashboards.

4. Confirm auth works

Hit the /v1/me endpoint to check your key and pick up the rate-limit / API-version response headers:

curl -i https://watchtraderhub.com/api/v1/me \
  -H "Authorization: Bearer wth_YOUR_API_KEY"

You should get back a JSON body like:

{
  "object": "integration",
  "user_id": "…",
  "is_enabled": true,
  "is_test_mode": true,
  "api_version": "2026-05-07",
  "subscribed_events": ["*"],
  "webhook": {
    "url": "https://your-site.com/webhooks/wth",
    "last_success_at": null,
    "last_failure_at": null,
    "consecutive_failures": 0
  }
}

5. Trigger a test webhook

Fire a signed test event at your webhook URL. Test events ignore subscription filters by design, so you can verify wiring without tripping any business logic.

curl -X POST https://watchtraderhub.com/api/v1/test/webhook_ping \
  -H "Authorization: Bearer wth_YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Response: 202 Accepted with a delivery_id. Within ~60 seconds you should see a POST land at your webhook URL with these headers:

POST /webhooks/wth HTTP/1.1
X-WTH-Signature: t=1778229903,v1=5a81dbf590e046237fd578e75f5824f210fff7bf4cabd6de7a767169362b5044
X-WTH-Event-Id: evt_b6d0dfb9dfb64613bed8709ba8a5d079
X-WTH-Event-Type: integration.test_event
X-WTH-Delivery-Id: 55fbd03c-5744-4b8e-a057-a29af4729317
X-WTH-Delivery-Attempt: 1
Content-Type: application/json

On the dashboard, the Deliveries tab shows the delivery flip from pending to delivered with last-response-status 200. If it stays at failed, check that your receiver returns a 2xx within 10 seconds.

6. Pull your listings

Toggle a few inventory items onto the custom channel from the dashboard's inventory list (the Channels column on each row). Then:

curl -s https://watchtraderhub.com/api/v1/listings?limit=10 \
  -H "Authorization: Bearer wth_YOUR_API_KEY"

You'll get a cursor-paginated list:

{
  "object": "list",
  "data": [
    {
      "id": "24f0ebb1-…",
      "object": "listing",
      "status": "active",
      "watch": { "brand": "Rolex", "model": "Submariner Date", "reference": "116610LN", … },
      "price": { "amount": 1200000, "currency": "USD", "amount_formatted": "$12,000.00" },
      "photos": [],
      "created_at": "…",
      "updated_at": "…"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

See Pagination for how to walk a long list without missing or duplicating rows.

7. Verify the webhook signature

Before going live, verify the incoming signature on at least one delivery. The Webhooks page has copy-pasteable verifiers in cURL, Node.js, and PHP. Do not skip this. Without verification, anyone who guesses your URL can spoof events.

8. Switch off test mode

Once your end-to-end tests pass, flip Test mode off in Settings. Live data starts flowing on the next request. See Test mode for what the flag actually controls.