Documentation / Developers

Search titles and the full text of every guide.

    Browse guides
    DocumentationUsed by both institution types

    Webhooks, signatures and retries

    Validate the raw delivery, handle duplicates and recover alongside API polling.

    For: Integration developersReviewed

    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.

    Need a hand?

    Tell us which step you are working on and what you see.

    Contact the team →