CONNECT

Webhooks

A webhook sends results to your own system the moment they happen, so your records stay up to date without polling. You give Peridot an HTTPS address and the events you want; Peridot sends a signed POST for each one.

Events

Event	Sent when
`lab.started`	A learner opens a lab.
`task.completed`	A step is checked and passes.
`lab.completed`	Every step in a lab has passed.
`test.passed`	A chapter test is passed.
`test.failed`	A test attempt is below the pass mark.
`test.locked`	The learner can’t try that test again.

Add a webhook

With an API key or signed in as an org admin, send the URL and the events. The answer includes a signing secret, shown once.

Subscribe to lab and test results

POST /v1/webhooks
Authorization: Bearer pk_7Hq2…
Content-Type: application/json

{ "url": "https://records.lcu.edu.ng/peridot", "events": ["lab.completed", "test.passed", "test.failed"] }

201 Created
{ "webhook": { "id": "wh_…", "url": "https://records.lcu.edu.ng/peridot", "active": true, … },
  "secret": "whsec_…" }

What arrives

A lab.completed delivery

POST /peridot
Peridot-Event: lab.completed
Peridot-Delivery: dl_…
Peridot-Signature: t=1762684800,v1=5f2c…

{ "id": "ev_…", "event": "lab.completed", "occurred_at": "2026-11-09T10:42:00Z",
  "student": "LCU/2026/0412", "course": "CSC 111", "lab": "csc111-3.2",
  "passed": true, "attempt": 1, "tasks": { "done": 4, "total": 4 } }

Check the signature

The Peridot-Signature header holds a time t and a signature v1. To check a request, join t, a full stop and the raw request body, compute the HMAC-SHA256 of that with your secret, and compare it in hex with v1. Reject the request if they differ or if t is old.

How your server checks that a delivery came from Peridot.

Retries and the delivery log

Answer with any 2xx status to accept a delivery. Anything else, or no answer, is retried with a growing wait between tries, starting at 30 seconds, up to 8 tries. Every try is logged: see them with GET /v1/webhooks/ followed by the webhook’s id and /deliveries.

Retries: the wait doubles each time until the delivery is accepted or 8 tries are used.