Webhooks

Request basics

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

Headers

Useful headers for verification and debugging:

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

Event types

Internal DB enums and public event names:

Security notes

Verify signature, validate timestamp and treat payloads defensively.

Signature verification

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

Replay protection

Reject requests with stale timestamps (e.g. > 5 minutes).

Node.js example

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

Python example

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

Sample payload

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

Troubleshooting

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