Webhooks, signatures and retries
Validate the raw delivery, handle duplicates and recover alongside API polling.
Create an HTTPS endpoint in Settings → Developers, select event types and save the signing secret. Use Send test and inspect delivery records before relying on the integration. Delivery occurs asynchronously after the related business change commits.
Events and envelope
Supported events are student.created, student.updated, enrollment.created, invoice.issued, payment.recorded, payment.refunded, results.published and webhook.test. Query GET /api/public/v1/events for the deployed catalogue.
{
"id": "evt_example",
"type": "payment.recorded",
"created_at": "2026-10-23T09:00:00+00:00",
"data": { "payment": { "id": "example", "amount_minor": 10000, "currency": "NGN" } }
}
This is an abbreviated envelope, not a complete payment schema. Resource payloads follow the corresponding public representation. Treat event and delivery identifiers as opaque strings.
Verify before processing
Read X-Takadar-Signature in the form t=<unix timestamp>,v1=<hex digest>. Compute HMAC-SHA256 over the timestamp, a dot and the exact raw request bytes. Reject timestamps outside the 300-second tolerance and compare signatures in constant time. Do not parse and reserialize JSON before verification.
import hashlib
import hmac
import time
def verify_webhook(secret: str, raw_body: bytes, header: str, *, now=None) -> bool:
try:
parts = dict(part.split("=", 1) for part in header.split(","))
timestamp = int(parts["t"])
presented = parts["v1"]
except (ValueError, KeyError):
return False
current = time.time() if now is None else now
if abs(current - timestamp) > 300:
return False
signed = str(timestamp).encode("ascii") + b"." + raw_body
expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, presented)
Read the raw body from your framework before its JSON middleware changes it. Validate, durably enqueue the event and return a successful HTTP response. Perform slow work separately.
Handle duplicates and recover
Deduplicate by envelope event ID. A delivery header identifies the delivery, while the event ID lets you avoid applying the same event twice. Design processing to tolerate replay and ambiguous network outcomes.
The worker allows up to six delivery attempts with backoff. Ten consecutive deliveries that exhaust their attempts disable the endpoint; a successful delivery resets the failure streak. Inspect delivery status, fix the cause and use the permitted replay or re-enable action. Rotating the secret replaces it, so coordinate the receiver update.
Poll as well
Bulk student imports do not emit an individual event for every row. There is no time-range replay feed; replay is per delivery. Use the public API’s inclusive delta filter alongside webhooks and periodically reconcile your local data.
Production endpoint URLs require HTTPS and publicly routable destinations. Private or local addresses are rejected, DNS is checked at send time, and redirects are not followed. A reachable HTTPS receiver is necessary; saving the URL alone does not prove a successful delivery.