Dokumentation

Webhooks

Webhooks informieren dein System in Echtzeit ueber Ereignisse. Du hinterlegst eine URL und abonnierst Ereignisse; Certifylize sendet dann HTTP-POST-Requests.

Anfrage-Grundlagen

POST + application/json
User-Agent: Certifylize-Webhooks/1.0
Body = JSON event envelope

Headers

Nuetzliche Header fuer Verifikation und Debugging:

x-certifylize-signature
x-certifylize-timestamp
x-certifylize-delivery-id
x-certifylize-event-type
x-certifylize-attempt

Ereignistypen

Interne DB-Enums und oeffentliche Eventnamen:

Oeffentliches Ereignis	DB-Enum	Beschreibung
edu.api_key.created	EDU_API_KEY_CREATED	Neuer API-Schluessel erstellt.
edu.api_key.revoked	EDU_API_KEY_REVOKED	API-Schluessel widerrufen.
edu.credential.issued	EDU_CREDENTIAL_ISSUED	Nachweis neu ausgestellt.
edu.credential.revoked	EDU_CREDENTIAL_REVOKED	Nachweis widerrufen.
edu.credential.updated	EDU_CREDENTIAL_UPDATED	Nachweis aktualisiert.

Sicherheitshinweise

Verifiziere Signatur, pruefe Timestamp und behandle Eingaben defensiv.

Signaturpruefung

message = <timestamp>.<rawBody>
expected = sha256=<hex(HMAC_SHA256(secret, message))>

Replay-Schutz

Lehne Requests mit zu alter Timestamp-Differenz ab (z. B. > 5 Minuten).

Node.js-Beispiel

import crypto from "crypto";
const message = ts + "." + rawBody;
const expected = crypto.createHmac("sha256", secret).update(message).digest("hex");

Python-Beispiel

message = f"{ts}.{raw}"
expected = hmac.new(secret, message.encode("utf-8"), hashlib.sha256).hexdigest()

Beispiel-Payload

{
  "id": "evt_...",
  "type": "edu.credential.issued",
  "createdAt": "2026-02-21T21:30:46.677Z"
}

Fehlersuche

Use raw body for signature verification.
Return 2xx quickly and process asynchronously.
Use delivery ID for idempotency.

Lokal testen mit http://127.0.0.1:8788/webhook und /webhooks/:id/test.