PaadamപാഠംGuides

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": { … } }
  • id is 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

EventWhen
member.createdSomeone was added: a learner, parent, tutor or admin
member.updatedSomeone's details, roles or status changed
enrollment.createdA learner joined a course (added by staff or by buying it)
enrollment.endedA learner left a course, was removed, or their access ended
course.createdA course was created
course.updatedA course's details changed
class.scheduledA class was scheduled
class.updatedA class was moved or changed
class.cancelledA class was cancelled
class.startedA class started
class.endedA class ended
attendance.markedAttendance for a class was marked or changed
recording.addedA class recording was added
test.submittedA learner handed in a test, quiz or assignment
test.gradedA test, quiz or assignment was marked
certificate.issuedA certificate was issued
order.createdAn order was created (a checkout, or a sale by staff)
payment.paidA payment was received
payment.refundedA payment was refunded
lead.createdAn enquiry came in
progress_report.publishedA progress report was published to a learner and their parents
announcement.sentAn announcement went out
form.submittedSomeone filled in one of the institute's forms
agreement.signedSomeone signed an agreement