WatchTraderHub Custom Integration API
Connect any custom website or platform to WatchTraderHub via a public REST API and outbound HMAC-signed webhooks. Bearer-token auth. Idempotent writes. Cursor pagination. Nothing fancy, nothing surprising.
What's in here
Core concepts
AuthenticationBearer keys, regeneration, rotation, lockout.IdempotencySafe retries via Idempotency-Key, replay semantics, body-hash mismatch behaviour.PaginationCursor format, after / updated_after, has_more, tie-break.Rate limits600 requests / minute by default. Headers, 429 backoff, raise-cap path.Test modeLive vs test data, dashboard visibility, the three flags that interact.ErrorsCatalog of every code the API can emit, causes and recovery.
Webhooks
Health endpoint
GET /api/v1/health is an unauthenticated liveness probe. It returns { "status": "ok", "api_version": "..." } and is intended for uptime monitors and load-balancer health checks. No rate limiting applies. No credentials required.
Auth, in one breath
Send Authorization: Bearer wth_YOUR_API_KEY on every request. Your key has the shape wth_ + 32 base62 characters and is generated from your custom integration settings in the dealer dashboard. Keep it server-side and treat it like a password.
Ground rules
- Test mode is on by default. Toggle it off only once your end-to-end tests pass against a real webhook.site (or similar) receiver. Test-mode rules.
- Every POST needs an
Idempotency-Key. Use the same key + body to safely retry. The second call returns the first result withIdempotent-Replay: true. Idempotency contract. - Verify webhook signatures. The
WTH-Signatureheader carries an HMAC-SHA256 over$timestamp.$rawBody. Verification recipes. - Cursor pagination. Pass
next_cursorback asafter. Never hand-craft one. Pagination.