How to get quiz answers into your own system with webhooks

Short answer: POST /quizzes/:id/webhook once with a URL and a secret. From then on, every completed response POSTs itself to you — no polling.

Set it up

curl -X POST https://quizgen.dev/api/v1/quizzes/qz_1f6b.../webhook \
  -H "Authorization: Bearer qg_live_..." \
  -H "Content-Type: application/json" \
  --data '{ "url": "https://your-endpoint.example.com/quizgen", "secret": "at-least-8-chars" }'

Send {"url": null} to remove it later.

What arrives

{ "event": "response.completed",
  "quiz": { "id": "qz_...", "slug": "x7km2p", "title": "..." },
  "response": { "id": "rsp_...", "answers": { "...": "..." },
                "outcome": "qualified", "score": 7,
                "respondent_email": null,
                "started_at": "...", "completed_at": "..." } }

If your form uses outcomes, outcome and score come along for free — useful for routing (send only qualified responses to Slack, say) without re-implementing the scoring logic on your end.

Verify it's really QuizGen

Every request carries an X-QuizGen-Signature header: the HMAC-SHA256 hex digest of the raw request body, signed with the secret you set. Verify it before trusting the payload:

const crypto = require("crypto");

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Use the raw request body for this — parsing it to JSON and re-serializing before checking will produce a different byte string and fail the check.

Delivery and retries

If your endpoint returns a 5xx or the request fails outright, QuizGen retries twice, then gives up — it won't retry indefinitely. Treat response.id as an idempotency key on your side in case a retry and an original delivery both land.

---

Full webhook reference: quizgen.dev/llms.txt.