RECEIVE STUDY RESULTS.

Steps

1. 1. Get a key

   Workspace admins issue keys in the app at /app/api-keys. Start with a sandbox key: it is bound to a showroom workspace and can never touch live data. Keep the secret server-side.

   export QN_API_KEY="qn_sandbox_…"
   curl "$QN_BASE/me" -H "Authorization: Bearer $QN_API_KEY"

2. 2. Register an endpoint

   Add an HTTPS endpoint in the app and subscribe it to the research events you care about. You get a signing secret once.

3. 3. Verify every delivery

   We sign <timestamp>.<body> with HMAC-SHA256 and send QN-Signature plus the timestamp. Reject anything older than five minutes and compare in constant time. During a secret rotation both the old and the new signature are sent, so accept either.

   import { createHmac, timingSafeEqual } from "node:crypto";
   
   const expected = createHmac("sha256", secret)
     .update(`${timestamp}.${rawBody}`)
     .digest("hex");
   const ok = timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

4. 4. Read the finding

   The delivery carries the finding id. Fetch the full record, including the study, the sample size and whether it has been validated, from GET /findings.

   curl "$QN_BASE/findings?limit=20" -H "Authorization: Bearer $QN_API_KEY"

5. 5. Replay when you break

   Deliveries you failed stay in the log. Replay one with the same event id from the app or POST /webhook-deliveries/{id}/replay, and make your handler idempotent on the event id.