# 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

```bash
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

```json
{ "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:

```js
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](/llms.txt#webhooks).