Plug QWTN into the rest of your business

Authentication and scopes

Keys look like qwtn_live_XXXXXXXX_…. The first part (the prefix) is shown in the app so you can tell keys apart; we store only a SHA-256 hash of the rest. Keys belong to the team, can expire, and can be revoked instantly. Requests with a missing, revoked or expired key get 401; a key without the right scope gets 403 insufficient_scope.

A :write scope includes :read for the same records. GET /api/v1/me tells you which team and scopes a key has.

Requests and errors

Send JSON bodies with Content-Type: application/json. Unknown fields are rejected so typos never pass silently. Dates are YYYY-MM-DD, timestamps ISO 8601 UTC, money in pounds as numbers. Every response carries an X-Request-Id; quote it if you contact us.

Errors always have the same shape. Branch on code, not the message:

HTTP/1.1 422 Unprocessable Entity
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "The request body has invalid fields",
    "request_id": "req_8b0153f6deef40de9fb0",
    "details": [{ "field": "ewc_codes", "message": "Required" }]
  }
}

Codes: unauthenticated, invalid_api_key, insufficient_scope, not_found, validation_failed, invalid_cursor, rate_limited, idempotency_conflict, idempotency_in_progress, internal_error.

Pagination

Lists return up to limit items (1–100, default 25), newest first. When has_more is true, pass next_cursor back as cursor. Cursors are stable while new records arrive, so you never skip or repeat a row. For incremental sync of notes use updated_after.

let cursor = null
do {
  const url = new URL('https://qwtn.co.uk/api/v1/collections')
  url.searchParams.set('status', 'completed')
  if (cursor) url.searchParams.set('cursor', cursor)
  const page = await fetch(url, { headers: { Authorization: `Bearer ${process.env.QWTN_API_KEY}` } }).then((r) => r.json())
  for (const job of page.data) handle(job)
  cursor = page.next_cursor
} while (cursor)

Idempotency

Send an Idempotency-Key header (any unique string, e.g. a UUID) on every POST and PATCH. If the network drops and you retry with the same key within 24 hours, you get the original response back with Idempotent-Replayed: true instead of a duplicate note or ticket. Reusing a key with a different body returns 422 idempotency_conflict.

curl -X POST https://qwtn.co.uk/api/v1/notes \
  -H "Authorization: Bearer $QWTN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c0f2a1e-job-8812" \
  -d '{
    "waste_description": "Mixed construction and demolition waste",
    "ewc_codes": ["17 09 04"],
    "client_id": "e913a8a6-ffe2-47c4-9686-f25938ae9154",
    "weight_kg": 1200,
    "transfer_date": "2026-10-14"
  }'

Rate limits

120 requests per minute per key. Over the limit you get 429 rate_limited with a Retry-After header in seconds. Back off and retry; bulk jobs should page through lists rather than fetching records one by one.

Endpoints

Base URL https://qwtn.co.uk. Full field-level detail is in the OpenAPI 3.1 document (import it into Postman, Insomnia or a code generator).

Webhooks

Add HTTPS endpoints in Settings → Webhooks and choose the events to receive. Each event is a JSON POST whose data.object is the record exactly as the REST API returns it.

POST /your/endpoint
QWTN-Signature: t=1760262000,v1=5f2b…c9
QWTN-Event-Id: evt_6a1f…
QWTN-Event-Type: invoice.paid

{ "id": "evt_6a1f…", "object": "event", "type": "invoice.paid", "api_version": "2026-10-01",
  "created_at": "2026-10-12T09:40:00Z", "data": { "object": { "id": "…", "object": "invoice", "status": "paid", … } } }

Verify the signature

Compute HMAC-SHA256 of `${t}.${rawBody}` with your endpoint secret and compare it, in constant time, with any v1 value. Reject timestamps more than five minutes old. During a secret rotation the header carries two v1 values for 24 hours.

import crypto from 'node:crypto'

app.post('/webhooks/qwtn', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('QWTN-Signature') ?? ''
  const t = Number(/t=(\d+)/.exec(header)?.[1])
  const expected = crypto.createHmac('sha256', process.env.QWTN_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`).digest('hex')
  const ok = Math.abs(Date.now() / 1000 - t) < 300 &&
    [...header.matchAll(/v1=([0-9a-f]{64})/g)].some(([, sig]) =>
      crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex')))
  if (!ok) return res.status(400).end()
  const event = JSON.parse(req.body)
  // dedupe on event.id, then queue your work and reply fast
  res.sendStatus(204)
})

Delivery and retries

• Reply with any 2xx within 10 seconds. Do slow work after replying.
• Anything else is retried after 1m, 5m, 30m, 2h, 6h, 12h, 24h, 24h (with jitter), then marked failed. Retries are at-least-once: dedupe on id.
• Replying 410 Gone disables the endpoint; 15 events in a row that exhaust their retries also disable it.
• The delivery log in Settings shows every attempt, payload and response, and lets you replay any event or send a test ping.
• Order is not guaranteed. Use created_at and fetch the record from the API if you need the latest state.

Built-in integrations

• Stripe and GoCardless: pay-now links on invoices that settle into your own account; invoices are marked paid automatically.
• CSV import and full export: clients, client sites, containers and vehicles in; every record type out as a ZIP of CSVs.

Versioning and support

This is API version 2026-10-01 (sent as the QWTN-Version response header). We add fields and endpoints without notice, so ignore fields you do not recognise. Breaking changes get a new version and at least six months’ notice by email to account owners. Questions: support@qwtn.co.uk.