API usage and setup guide

Node.js fetch example

const res = await fetch("https://api.needine.com/certificates?page=1&pageSize=10", {
  headers: {
    "X-API-Key": process.env.NEEDINE_API_KEY,
    "Content-Type": "application/json"
  }
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

JavaScript SDK

import { NeedineClient } from "@needine/sdk";

const client = new NeedineClient({ apiKey: process.env.NEEDINE_API_KEY });
const created = await client.createCertificate({
  certificateType: "ai_report",
  signerName: "Maria Lopez",
  issuingCompany: "Acme Consulting",
  inputEvidence: [{ sha256Hash: "b7c4...", evidenceType: "input" }],
  outputEvidence: [{ sha256Hash: "a99d...", evidenceType: "output" }],
  model: { provider: "openai", modelName: "gpt-4o" }
});

const verification = await client.verifyCertificate(created.certificateId);
console.log(created.certificateId, verification.valid, verification.trustLevel);

Python SDK

from needine import NeedineClient

client = NeedineClient(api_key="ndi_xxx", base_url="https://api.needine.com")
created = client.create_certificate({
    "certificateType": "ai_report",
    "signerName": "Maria Lopez",
    "issuingCompany": "Acme Consulting",
    "inputEvidence": [{"sha256Hash": "b7c4...", "evidenceType": "input"}],
    "outputEvidence": [{"sha256Hash": "a99d...", "evidenceType": "output"}],
    "model": {"provider": "openai", "modelName": "gpt-4o"}
})

verification = client.verify_certificate(created["certificateId"])
print(created["certificateId"], verification["valid"], verification["trustLevel"])

Supported event names

certificate.issued,certificate.revoked,anchor.confirmed,trust.updated

Current production triggers actively dispatch certificate lifecycle events:certificate.issuedandcertificate.revoked.

Delivery contract

• - Method: POST
• - Content-Type: application/json
• - Timeout per attempt: 10s
• - Retries: 3 attempts with backoff 1s, 4s, 9s
• - Success criteria: any HTTP 2xx response
• - Recommended receiver behavior: idempotent processing keyed by event + certificate ID.

Signature verification (Node.js)

import crypto from "crypto";

// Store and protect the raw secret returned once at webhook creation (whsec_...)
const rawSecret = process.env.NEEDINE_WEBHOOK_SECRET;
const signatureHeader = req.headers["x-needine-signature"]; // sha256=<hex>
const rawBody = requestRawBodyAsString; // do not reserialize JSON

const signingKey = crypto.createHash("sha256").update(rawSecret).digest("hex");
const expected = crypto.createHmac("sha256", signingKey).update(rawBody).digest("hex");
const received = String(signatureHeader || "").replace("sha256=", "");

if (!crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(received, "hex"))) {
  throw new Error("Invalid webhook signature");
}

Signature verification (Python)

import hashlib
import hmac

raw_secret = os.environ["NEEDINE_WEBHOOK_SECRET"]
signature_header = request.headers.get("X-Needine-Signature", "")
raw_body = request.get_data(as_text=True)  # exact raw body

signing_key = hashlib.sha256(raw_secret.encode()).hexdigest()
expected = hmac.new(signing_key.encode(), raw_body.encode(), hashlib.sha256).hexdigest()
received = signature_header.replace("sha256=", "")

if not hmac.compare_digest(expected, received):
    raise ValueError("Invalid webhook signature")