For developers
Webhooks
Get told the moment something happens: a payment, a new learner, a class ending, a form sent.
Add an address in Settings → Developers → New webhook, pick the events you want (or every event, including ones added later), and copy the signing secret. Paadam then POSTs each event there as it happens.
What arrives
POST /your/hook HTTP/1.1
content-type: application/json
x-paadam-event: payment.paid
x-paadam-event-id: 3f5e…
x-paadam-delivery: 9a1c…
x-paadam-timestamp: 1791626400
x-paadam-signature: 5d4b…
{ "id": "3f5e…", "event": "payment.paid", "createdAt": "2026-10-10T09:20:00.000Z",
"institute": { "slug": "sunrise", "name": "Sunrise Academy" },
"data": { … } }idis the same for every delivery of one event: use it to ignore repeats.- Answer with any 2xx status within 10 seconds. Anything else is tried again after 1, 5, 30 minutes, 2, 6 and 12 hours and a day (eight tries in all).
- An address that keeps failing for three days, or answers 410 Gone, is switched off; you'll see why in Settings.
- Every delivery, with the answer it got, is kept for 30 days under Deliveries, and Send a test sends a
ping.
Check it came from Paadam
The signature is a hex HMAC-SHA256 of the timestamp, a dot, and the raw body, keyed with your signing secret. Refuse anything with a wrong signature or a timestamp more than five minutes old.
Node.js (Express)
import { createHmac, timingSafeEqual } from "node:crypto";
app.post("/paadam", express.raw({ type: "application/json" }), (req, res) => {
const ts = req.header("x-paadam-timestamp");
const sig = req.header("x-paadam-signature") ?? "";
const want = createHmac("sha256", process.env.PAADAM_WEBHOOK_SECRET).update(ts + "." + req.body).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
if (!fresh || sig.length !== want.length || !timingSafeEqual(Buffer.from(sig), Buffer.from(want))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body);
// …
res.sendStatus(200);
});PHP
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_PAADAM_TIMESTAMP'] ?? '';
$want = hash_hmac('sha256', $ts . '.' . $body, getenv('PAADAM_WEBHOOK_SECRET'));
if (abs(time() - (int) $ts) > 300 || !hash_equals($want, $_SERVER['HTTP_X_PAADAM_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);Python
import hashlib, hmac, os, time
def is_from_paadam(headers, body: bytes) -> bool:
ts = headers.get("x-paadam-timestamp", "")
want = hmac.new(os.environ["PAADAM_WEBHOOK_SECRET"].encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
return abs(time.time() - int(ts or 0)) < 300 and hmac.compare_digest(want, headers.get("x-paadam-signature", ""))Events
| Event | When |
|---|---|
member.created | Someone was added: a learner, parent, tutor or admin |
member.updated | Someone's details, roles or status changed |
enrollment.created | A learner joined a course (added by staff or by buying it) |
enrollment.ended | A learner left a course, was removed, or their access ended |
course.created | A course was created |
course.updated | A course's details changed |
class.scheduled | A class was scheduled |
class.updated | A class was moved or changed |
class.cancelled | A class was cancelled |
class.started | A class started |
class.ended | A class ended |
attendance.marked | Attendance for a class was marked or changed |
recording.added | A class recording was added |
test.submitted | A learner handed in a test, quiz or assignment |
test.graded | A test, quiz or assignment was marked |
certificate.issued | A certificate was issued |
order.created | An order was created (a checkout, or a sale by staff) |
payment.paid | A payment was received |
payment.refunded | A payment was refunded |
lead.created | An enquiry came in |
progress_report.published | A progress report was published to a learner and their parents |
announcement.sent | An announcement went out |
form.submitted | Someone filled in one of the institute's forms |
agreement.signed | Someone signed an agreement |