Connect your platform to Gradally's answer grading

Three ways to connect

Options mix: a platform can start with A and add the webhook later, or use B for intake and C's feed for audit. The identifiers are the same everywhere: your attempt reference plus your question reference name one answer slot, and each content change is a new version.

Option A · Zero-work connector

Gradally runs a connector on its side that polls your answers table every 15 seconds, admits every new or changed answer through the same rules as the API (one version per content change, approved key only), grades it, and mirrors the current result into one dedicated table in your database. Your application reads that table.

What we need from you

1. Read access to the table or view that holds typed answers: a database user that can only SELECT it. Tell us the database product (PostgreSQL, MySQL or SQL Server), host, port, database name, and send the password over a separate channel.
2. Five columns in that table or view: a monotonic row id, the attempt (or submission) reference, your question reference, the answer text, and a last-updated time. An exam reference column lets us filter one exam per stream. Gradally selects only these columns; names, phones and e-mails are never read.
3. One results table created from the DDL below, with a user that can INSERT and UPDATE it. Gradally never touches your business tables.
4. Network: allow Gradally's public IPv4 address to reach the database over TLS (verified certificate; we accept your CA file), or a replica if you prefer.
5. The question mapping: which of your question references corresponds to each Gradally question, agreed once per exam.

The results table Gradally writes

CREATE TABLE gradally_results (
  submission_ref      VARCHAR(160) NOT NULL,   -- "<attempt>:<your question ref>"
  submission_version  INTEGER      NOT NULL,   -- 1, 2, … per content change
  attempt_ref         VARCHAR(70),
  question_ref        VARCHAR(70),
  state               VARCHAR(20)  NOT NULL,   -- ready | processing | unavailable | …
  fraction            VARCHAR(16),             -- decimal strings; NULL when no grade
  earned              VARCHAR(16),
  maximum             VARCHAR(16),
  feedback            TEXT,
  result_digest       CHAR(64)     NOT NULL,   -- changes whenever the row changes
  updated_at          TIMESTAMPTZ  NOT NULL,
  PRIMARY KEY (submission_ref, submission_version)
);

CREATE TABLE gradally_results (
  submission_ref      VARCHAR(160) NOT NULL,
  submission_version  INT          NOT NULL,
  attempt_ref         VARCHAR(70),
  question_ref        VARCHAR(70),
  state               VARCHAR(20)  NOT NULL,
  fraction            VARCHAR(16),
  earned              VARCHAR(16),
  maximum             VARCHAR(16),
  feedback            TEXT,
  result_digest       CHAR(64)     NOT NULL,
  updated_at          VARCHAR(40)  NOT NULL,
  PRIMARY KEY (submission_ref, submission_version)
) CHARACTER SET utf8mb4;

How to read it

• The usable grade of an answer slot is the row with the highest submission_version whose state is ready. Older versions are marked superseded and keep NULL scores.
• fraction, earned and maximum are decimal strings (for example "0.5", "1", "2"); NULL never means zero.
• A row can change from ready to stale or unavailable after a key correction; watch result_digest or updated_at, not only new rows.
• States and their meaning are the same six as in the API: see Results & states.

Recorded: on the sandbox the connector pulled 3 rows of the configured exam (a fourth row of another exam was filtered out), admitted the 2 mapped answers, skipped the one with an unknown question reference, and after the grading pass wrote their result rows as ready. An edited answer was then picked up as version 2 with version 1 marked superseded, and after the next grading pass version 2 was written as ready. Its SQL never named the personal columns present in the table.

Option B · Two calls and a signed webhook

Your server makes one call when a student submits (POST /answers/, one answer per request) and receives one signed POST from Gradally whenever a result changes. Nothing else is required; the feed and result reads in Option C stay available for audit and recovery.

What we need from you

• An HTTPS receiver URL (no query string, no credentials in the URL) and its public IPv4 address. Gradally connects to that pinned address with a verified certificate for your hostname; private addresses, IPv6 and redirects are refused.
• Somewhere safe to keep two secrets we deliver separately: the stream bearer for your calls and the webhook signing secret for ours.

Verify, store, then answer 2xx

POST /your/receiver HTTP/1.1
Content-Type: application/json
User-Agent: Gradally-Result-Webhook/1
X-Gradally-Webhook-Id: 33333333-3333-4333-8333-333333333333
X-Gradally-Webhook-Timestamp: 1789992000
X-Gradally-Webhook-Signature: sha256=<hex HMAC-SHA256>

signature = HMAC-SHA256(secret, ASCII(timestamp) + "." + raw body bytes)

{
  "schema_version": "sanad-result-webhook-1",
  "event_id": "33333333-3333-4333-8333-333333333333",
  "stream_id": "11111111-1111-4111-8111-111111111111",
  "sequence": 1,
  "receipt_id": "22222222-2222-4222-8222-222222222222",
  "observed_at": "2026-09-17T12:00:00+00:00",
  "result_url": "/api/v1/streams/11111111-1111-4111-8111-111111111111/results/22222222-2222-4222-8222-222222222222/",
  "publishable": false,
  "result": { …the same Result object as GET /results/{receipt_id}/… }
}

1. Reject bodies over 262,144 bytes. Compute the HMAC over the untouched bytes with the timestamp header; compare in constant time; require the timestamp within 300 seconds of your clock.
2. Check schema_version, your stream_id, that event_id equals the header, and publishable: false.
3. Insert a durable inbox row keyed by (stream_id, event_id) and commit. Only then answer 204 (any 2xx). A duplicate already stored gets the same 2xx. If you cannot store right now, answer 503.
4. Apply result per answer slot in your worker: the highest version wins; non-ready states invalidate an earlier grade; null is never zero.

Delivery is at least once and in sequence per stream: retries keep event_id and sequence but refresh observed_at and result. Gradally retries network failures and 408, 425, 429 and 5xx with backoff for up to eight attempts; any other non-2xx stops that stream's queue until the Gradally operator retries it, so keep the endpoint boring: verify, store, 2xx. A 2xx confirms transport only; it is neither an acknowledgement nor permission to publish.

The reference client in the kit (partner_api_client.py, function verify_webhook) implements exactly these checks.

Before production

All three options are implemented and tested, but the service is not yet in production. Still to be done, in order:

1. A reachable HTTPS sandbox for your team, with a prepared exam, a stream and its credentials; then the mapping of your question references.
2. For A: the database grants and the results table; for B: your receiver and its public address.
3. The acceptance run on synthetic answers (checklist), then a shadow period on real answers with grades kept out of students' view.
4. The publication agreement: until then every result carries publishable: false and your student-facing grade stays as it is.

Option C · Connection & credentials

Base path

https://<assigned-origin>/api/v1/streams/{stream_id}/. All paths end with a slash.

Authentication

Authorization: Bearer <stream secret> on every request. No cookies, no CSRF token, no login.

Content

Requests with a body: Content-Type: application/json, UTF-8. Send Accept: application/json.

Transport

HTTPS with certificate verification. In production a plain-HTTP request is refused with 400 https_required. Do not follow redirects while carrying the Authorization header.

Caching

Every response is Cache-Control: private, no-store. Result reads carry an ETag equal to the quoted result_digest; conditional requests (304) are not implemented.

Secret handling

Keep the secret in your server's secret store. Never put it in a browser, a mobile app, a URL or a log line. Rotation by the Gradally operator revokes the previous secret immediately, with no overlap window.

Scope

The secret authenticates one stream only. A receipt, cursor or token from another stream is rejected (404/400/409); there is no header that switches institutions.

The flow

1. Outbox. In the same transaction that accepts a submission, store an outbox row with the immutable payload (IDs, version, fingerprint, text) and your private mapping to student and attempt.
2. Send. A sender posts the row to answers/. On 202 or 200 store the receipt_id and mark the row delivered. On a timeout, replay the exact same payload: it returns the same receipt.
3. Follow. A consumer polls changes/ with its saved cursor (or your webhook receiver queues the event). For each change it fetches the current result, stores it as the shadow grade for that answer version, and commits the cursor in the same transaction.
4. Acknowledge. When a stored result is ready and applied, post the acknowledgement with the result's digest and delivery token. Replaying the same acknowledgement is safe.
5. Revisions. If the student edits, send version 2. Version 1's result becomes superseded; only the latest version carries a usable grade.

Endpoints

All seven live under /api/v1/streams/{stream_id}/. The bodies below are the recorded responses of the run.

GET /api/v1/streams/{stream_id}/
Authorization: Bearer <stream secret>
Accept: application/json

{
  "schema_version": "sanad-partner-stream-1",
  "stream_id": "b27ad65b-07cf-443f-b326-35ac6a75e32b",
  "exam_id": "preview-api-2026",
  "questions": [
    {"question_id": "MCQ-01", "question_fingerprint": "8ee906b36a198f7cd37c1fa930cfc46f5a35b8df87a2a8505253d4265e47aa0a", "context_approved": true, "max_mark": "1"},
    {"question_id": "NUM-01", "question_fingerprint": "1d61a0e4b019681a2bb75cfd4fcd119a770c0415eb6a1d72da93aab93a00941c", "context_approved": true, "max_mark": "2"}
  ]
}

POST /api/v1/streams/{stream_id}/answers/
Authorization: Bearer <stream secret>
Content-Type: application/json
Idempotency-Key: outbox-row-77        (optional)

{
  "schema_version": "sanad-submission-1",
  "submission_id": "attempt-9001-mcq01",
  "submission_version": 1,
  "question_id": "MCQ-01",
  "question_fingerprint": "8ee906b36a198f7cd37c1fa930cfc46f5a35b8df87a2a8505253d4265e47aa0a",
  "text": "b",
  "has_attachment": false
}

{
  "schema_version": "sanad-receipt-1",
  "receipt_id": "d0ec959e-0e63-4705-a5ed-444b77a708ea",
  "submission_id": "attempt-9001-mcq01",
  "submission_version": 1,
  "created": true,
  "result_url": "/api/v1/streams/b27ad65b-07cf-443f-b326-35ac6a75e32b/results/d0ec959e-0e63-4705-a5ed-444b77a708ea/"
}

{
  "schema_version": "sanad-partner-result-1",
  "receipt_id": "d0ec959e-0e63-4705-a5ed-444b77a708ea",
  "submission_id": "attempt-9001-mcq01",
  "submission_version": 1,
  "question_id": "MCQ-01",
  "question_fingerprint": "8ee906b36a198f7cd37c1fa930cfc46f5a35b8df87a2a8505253d4265e47aa0a",
  "grading_fingerprint": "8ee906b36a198f7cd37c1fa930cfc46f5a35b8df87a2a8505253d4265e47aa0a",
  "decision_revision": 0,
  "state": "processing",
  "message": "الإجابة قيد المعالجة.",
  "decision_applied": false,
  "publishable": false,
  "score": null,
  "criteria": [],
  "feedback": [],
  "result_digest": "7021bffc8a3769e9d5b4608ad7e3d9cc8b2a3593c670a548bde1aeb65f870471",
  "delivery_token": null
}

{
  "schema_version": "sanad-partner-result-1",
  "receipt_id": "d0ec959e-0e63-4705-a5ed-444b77a708ea",
  "submission_id": "attempt-9001-mcq01",
  "submission_version": 1,
  "question_id": "MCQ-01",
  "question_fingerprint": "8ee906b36a198f7cd37c1fa930cfc46f5a35b8df87a2a8505253d4265e47aa0a",
  "grading_fingerprint": "8ee906b36a198f7cd37c1fa930cfc46f5a35b8df87a2a8505253d4265e47aa0a",
  "decision_revision": 1,
  "state": "ready",
  "message": "النتيجة جاهزة للاستلام.",
  "decision_applied": true,
  "publishable": false,
  "score": {"fraction": "1", "earned": "1", "maximum": "1"},
  "criteria": [],
  "feedback": [],
  "result_digest": "0cd8ffa7efb168943a004f207bfeb8c22c6e1223ef13ad12a1a5fad53062dbfc",
  "delivery_token": "EXAMPLE_ONLY_OPAQUE_TOKEN_VALID_600_SECONDS"
}

GET /api/v1/streams/{stream_id}/submissions/?submission_id=attempt-9001-mcq01
GET /api/v1/streams/{stream_id}/submissions/?submission_id=attempt-9001-mcq01&submission_version=1

{
  "schema_version": "sanad-result-page-1",
  "results": [ { …one Result object per receipt… } ],
  "next_cursor": "EXAMPLE_ONLY_OPAQUE_CURSOR",
  "has_more": false,
  "cursor_semantics": "received_submissions_only; poll individual receipts for changed results"
}

{
  "schema_version": "sanad-result-changes-1",
  "changes": [
    {"sequence": 1, "receipt_id": "d0ec959e-0e63-4705-a5ed-444b77a708ea", "result_url": "/api/v1/streams/b27ad65b-07cf-443f-b326-35ac6a75e32b/results/d0ec959e-0e63-4705-a5ed-444b77a708ea/"}
  ],
  "next_cursor": "EXAMPLE_ONLY_OPAQUE_CURSOR",
  "has_more": false,
  "publishable": false,
  "semantics": "coalesced_invalidation; fetch_current_receipt_result; replay_is_safe"
}

{
  "schema_version": "sanad-result-ack-1",
  "receipt_id": "d0ec959e-0e63-4705-a5ed-444b77a708ea",
  "submission_version": 1,
  "decision_revision": 1,
  "result_digest": "0cd8ffa7efb168943a004f207bfeb8c22c6e1223ef13ad12a1a5fad53062dbfc",
  "delivery_token": "EXAMPLE_ONLY_OPAQUE_TOKEN_VALID_600_SECONDS",
  "destination_record_id": "lms-shadow-row-41"
}

{
  "schema_version": "sanad-result-acknowledged-1",
  "ack_id": 1,
  "created": true,
  "result_digest": "0cd8ffa7efb168943a004f207bfeb8c22c6e1223ef13ad12a1a5fad53062dbfc",
  "publishable": false
}

Answer rules

• Exactly these seven fields. Extra fields, duplicate keys, NaN/Infinity are rejected with 400.
• Whole JSON body at most 98,304 bytes; larger bodies are 413. Do not split one answer into fragments.
• Optional header Idempotency-Key (1–160 chars of A-Za-z0-9._~-, for example your outbox row key): the same key with the same body returns the same receipt; the same key with a different body is a 409. The body alone already makes exact replays safe, so the header is a convenience.

Results & states

States

Unknown future states must be treated as unavailable; unknown additional fields must be ignored. A result can move from ready back to a non-ready state; the availability of a grade can change even when decision_revision stays equal, so store the digest and compare it, not the revision alone.

Feeds & cursors

• Persist one cursor per (stream, feed). Cursors are opaque, signed and scoped to the stream; a cursor from another stream or a damaged cursor is 400 invalid_request.
• Replay is safe: re-reading from an older cursor repeats notifications, and your storage must be idempotent per (receipt_id, result_digest).
• The receipt scan's next_cursor is null only while the stream has no receipts. The change feed always returns a cursor, even for an empty page.
• Recovering your own lost checkpoint: replay both feeds from an empty cursor with idempotent storage. No retention period is promised yet; confirm it during onboarding.

Acknowledgements

1. Fetch the current result. Check that it is ready, decision_applied: true, with a score and a delivery_token.
2. Store the exact snapshot (all fields, digest included) in your shadow table and commit, together with a stable destination record ID.
3. Post the acknowledgement built from the result's five fields plus your record ID. Expect 201; an identical replay returns 200.
4. On 409, mark the stored snapshot unconfirmed, fetch the current result again, update or invalidate the shadow value, and acknowledge the new snapshot if it is applied. After an ambiguous network failure, replay the same acknowledgement first.

Errors & retries

Application errors are JSON: {"error": "<code>", "message": "<diagnostic>"}. The error code is stable; the message (often Arabic, sometimes empty) is for humans. Proxies may answer with non-JSON bodies: branch on the HTTP status first.

Limits

Implementation blueprint (Options B and C)

A minimal, correct integration is four tables and three workers. With the webhook, the follower is replaced by your receiver plus a small worker that applies queued events.

Invariants to keep

• Versions per submission_id are sent strictly in order; version n+1 only after version n has a receipt.
• The payload bytes of a version never change after the outbox row is written.
• Only the latest version's result is displayed as the shadow grade; older versions keep history.
• Secrets and delivery tokens never appear in logs, tickets or exported Postman files.
• Your existing grade shown to students is untouched until a publication agreement exists.

Code samples

Two minimal clients showing the exact wire format. They omit persistence and retries on purpose; wire them to your outbox and worker loop.

Python 3 (standard library only)

# pip-free client: urllib + json. Run on the server, never in a browser.
import json, urllib.request, urllib.error

ORIGIN = "https://<assigned-origin>"
STREAM = "<stream_id>"
SECRET = load_from_your_secret_store()   # never hard-code

def call(method, suffix, body=None, headers=None):
    url = f"{ORIGIN}/api/v1/streams/{STREAM}/{suffix}"
    data = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
    h = {"Authorization": "Bearer " + SECRET, "Accept": "application/json"} | (headers or {})
    if data is not None:
        h["Content-Type"] = "application/json"
    req = urllib.request.Request(url, data=data, headers=h, method=method)
    try:
        with urllib.request.urlopen(req, timeout=15) as r:
            return r.status, json.loads(r.read()), dict(r.headers)
    except urllib.error.HTTPError as e:
        return e.code, json.loads(e.read() or b"{}"), dict(e.headers)

def submit(row):   # row = your outbox record
    status, body, head = call("POST", "answers/", {
        "schema_version": "sanad-submission-1",
        "submission_id": row.submission_id, "submission_version": row.version,
        "question_id": row.question_id, "question_fingerprint": row.fingerprint,
        "text": row.text, "has_attachment": False,
    }, {"Idempotency-Key": row.key})
    if status in (200, 202):
        return body["receipt_id"]            # store it, mark delivered
    if status == 409:
        raise Reconcile(body["error"])       # do not mutate identity
    if status == 429:
        raise RetryLater(int(head["Retry-After"]))
    raise Fatal(status, body)

def follow(cursor):
    status, page, _ = call("GET", f"changes/?limit=100&cursor={cursor}")
    for change in page["changes"]:
        s, result, _ = call("GET", f"results/{change['receipt_id']}/")
        store_shadow(result)                 # idempotent on (receipt_id, result_digest)
    return page["next_cursor"], page["has_more"]   # commit with the batch

def acknowledge(result, destination_record_id):
    assert result["state"] == "ready" and result["decision_applied"] and result["score"] and result["delivery_token"]
    return call("POST", "acknowledgements/", {
        "schema_version": "sanad-result-ack-1", "destination_record_id": destination_record_id,
        **{k: result[k] for k in ("receipt_id", "submission_version", "decision_revision", "result_digest", "delivery_token")},
    })

Node.js 18+ (fetch) and a webhook receiver

const ORIGIN = "https://<assigned-origin>", STREAM = "<stream_id>";
const SECRET = await secrets.get("gradally-stream");           // never in the client bundle
const base = `${ORIGIN}/api/v1/streams/${STREAM}/`;

async function call(method, suffix, body, extra = {}) {
  const res = await fetch(base + suffix, {
    method, redirect: "error",
    headers: { Authorization: `Bearer ${SECRET}`, Accept: "application/json",
               ...(body ? { "Content-Type": "application/json" } : {}), ...extra },
    body: body ? JSON.stringify(body) : undefined,
  });
  const text = await res.text();
  let json = null; try { json = JSON.parse(text); } catch {}   // proxies may return non-JSON
  return { status: res.status, json, retryAfter: res.headers.get("retry-after") };
}

export const submit = (row) => call("POST", "answers/", {
  schema_version: "sanad-submission-1",
  submission_id: row.submissionId, submission_version: row.version,   // integer literal
  question_id: row.questionId, question_fingerprint: row.fingerprint,
  text: row.text, has_attachment: false,
}, { "Idempotency-Key": row.key });

// Webhook receiver (Express-style). Verify on the RAW body, store, then 204.
import { createHmac, timingSafeEqual } from "node:crypto";
app.post("/gradally/results", express.raw({ type: "application/json", limit: "256kb" }), async (req, res) => {
  const ts = req.get("X-Gradally-Webhook-Timestamp"), sig = req.get("X-Gradally-Webhook-Signature") || "";
  if (!/^\d{1,12}$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
  const expected = "sha256=" + createHmac("sha256", WEBHOOK_SECRET).update(ts + ".").update(req.body).digest("hex");
  if (expected.length !== sig.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  if (event.stream_id !== STREAM || event.event_id !== req.get("X-Gradally-Webhook-Id") || event.publishable !== false) return res.sendStatus(400);
  try { await inbox.insertIgnoreDuplicate(event.stream_id, event.event_id, event); }   // durable, unique (stream_id, event_id)
  catch { return res.sendStatus(503); }
  res.sendStatus(204);
});

Acceptance checklist

Run these against the sandbox from your own server, queues and storage (Options B and C) or against your database (Option A). A manual tool run proves the wire format, not your integration.

• Option A: the connector's plan lists the agreed table, columns and mapping; the first run creates one receipt per mapped answer and none for other exams or unmapped questions.
• Option A: an edited answer appears as version 2 in the results table and version 1 reads superseded; a personal column added to the table is never read.
• Manifest with the right secret lists the agreed questions; a missing or wrong secret is 401.
• Version 1 → 202 and a stored receipt; the exact replay → 200 with the same receipt and no duplicate.
• Same ID and version with a different text → 409, previous answer intact.
• Version 3 before 2 → 409; wrong fingerprint → 409; extra field or attachment flag → 400.
• A burst above the allowance → 429 with Retry-After; the same request succeeds after the wait.
• Pending result reads as processing; after grading, the change feed (or the webhook) lists the receipt and the result is ready.
• Option B: a webhook with a bad signature or a stale timestamp is refused; a valid one is stored once and answered 2xx; a duplicate gets 2xx without a second inbox row.
• Paging through more than one page loses nothing; the receipt cursor and the change cursor are stored separately.
• A stored ready result acknowledged → 201; the identical replay → 200; a changed or expired one → 409 and the shadow value is refreshed.
• Sending version 2 supersedes version 1 (no score on version 1, its acknowledgement now 409); the shadow grade shows version 2 only.
• Every stored result and acknowledgement shows publishable: false; the student-facing grade did not change.

Recorded run

The exchanges behind this page, in order, from a synthetic sandbox exam with two questions. Statuses are the real responses.

The connector run (Option A) on the same sandbox, four turns: plan (read-only), pull (3 rows of the exam, 2 admitted, 1 unmapped skipped, the other exam's row never selected), deliver after grading (both ready), the edited row admitted as version 2 with version 1 marked superseded, and version 2 delivered as ready after the next grading pass.

FAQ

We cannot open our database to anyone. What then?

Option B: one outbound call per answer and one receiver for the signed webhook, both on your server. If your backend already exposes an endpoint listing answers changed since a time, the connector can use that instead of a table; tell us its shape.

Can we send a whole quiz in one request?

No. One answer version per request. Queue them and send with a few workers; the allowance is 600 per stream per minute. With Option A there is nothing to send.

How fast is a grade ready?

Grading is asynchronous and batched by size and by a short deadline. There is no completion SLA in this release; the change feed, the webhook or the results table tells you when a result changed.

What if our request times out after Gradally stored the answer?

Replay the exact payload: you get 200 with the same receipt. Or read submissions/?submission_id=… to recover it.

Can the grade change after we stored it?

Yes: a key correction, a revision by the student, or a later decision can invalidate it. You will see it in the change feed, the webhook or the results table; store the new snapshot. Never show an old value while resolving a 409.

Can we show the grade to students?

Not from this integration alone. Results are shadow grades (publishable: false) until a separate publication agreement; keep your current grade untouched.

Which data must we never send or expose?

Student names, e-mails, phone numbers, parent numbers, previous grades, files or images. IDs are opaque on your side; Gradally receives the answer text and its identifiers only. A page that opens another site with student details in the URL is not an integration path for grades.

Downloads

These files travel with this page in the kit folder and in GRADALLY_PARTNER_API_KIT_2026-09-17-r2.zip:

• openapi.json: OpenAPI 3.1.1 with all seven operations, the webhook event, schemas and error responses.
• postman.collection.json and postman.environment.json: ready-to-import requests with empty variables.
• examples.json: synthetic bodies for every schema, the webhook event included.
• INTEGRATION.en.md: the detailed English contract; README.ar.md and ACCEPTANCE.ar.md: the Arabic overview and joint acceptance plan.

The sandbox origin, the stream ID, the secrets and Gradally's public address are delivered separately by the Gradally operator; the placeholders in these files are not operational.