CertifylizeCertifylize
Documentazione

Webhooks

I webhook notificano il tuo sistema in tempo reale. Registri un URL e gli eventi; Certifylize invia richieste HTTP POST.

Fondamenti richiesta

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

Header

Header utili per verifica e debug:

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

Tipi di evento

Enum DB interni e nomi evento pubblici:

Evento pubblicoEnum DBDescrizione
edu.api_key.createdEDU_API_KEY_CREATEDAPI key created.
edu.api_key.revokedEDU_API_KEY_REVOKEDAPI key revoked.
edu.credential.issuedEDU_CREDENTIAL_ISSUEDCredential issued.
edu.credential.revokedEDU_CREDENTIAL_REVOKEDCredential revoked.
edu.credential.updatedEDU_CREDENTIAL_UPDATEDCredential updated.

Note di sicurezza

Verifica firma, timestamp e tratta i payload in modo difensivo.

Verifica firma

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

Protezione replay

Rifiuta richieste con timestamp troppo vecchio (es. > 5 minuti).

Esempio Node.js

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

Esempio Python

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

Payload di esempio

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

Risoluzione problemi

  • Use raw body for signature verification.
  • Return 2xx quickly and process asynchronously.
  • Use delivery ID for idempotency.
Test locale con http://127.0.0.1:8788/webhook e /webhooks/:id/test.