Webhooks

Bazat e kerkeses

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

Headers

Header te dobishem per verifikim dhe debug:

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

Llojet e eventeve

Enum-et e brendshme DB dhe emrat publik te eventeve:

Shenime sigurie

Verifiko firmen, timestamp dhe trajto payload-et ne menyre mbrojtese.

Verifikimi i firmes

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

Mbrojtje replay

Refuzo kerkesat me timestamp te vjeter (p.sh. > 5 minuta).

Shembull Node.js

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

Shembull Python

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

Payload shembull

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

Zgjidhja e problemeve

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