Docs SDKs & integrations

Webhooks

Forward ledger events into the tools your team already uses.

Webhooks turn ledger events into HTTP POSTs against URLs you own. Configure them per repo in Settings → Webhooks, or through the REST API. Every request is signed so you can verify the payload came from gridtrue.

Event payload

json

POST https://hooks.yourteam.com/gridtrue
X-gridtrue-Signature: t=1712345678, v1=MEUCIQD…
Content-Type: application/json

{
  "id": "evt_01H…",
  "type": "attestation",
  "org": "acme",
  "repo": "payments",
  "commit": "6f4a…d91",
  "predicate": "test:go",
  "identity": "cn=alice,ou=dev,o=acme",
  "result": { "status": "pass", "duration_ms": 4812 },
  "timestamp": "2026-04-22T17:12:58Z"
}

Verifying the signature

typescript

import crypto from "node:crypto";

function verify(req: Request, secret: string): boolean {
  const header = req.headers.get("X-gridtrue-Signature") ?? "";
  const [t, v1] = header.split(", ").map((p) => p.split("=")[1]);
  const signed = `${t}.${await req.text()}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signed)
    .digest("base64");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Event types

attestation: A new signed attestation landed on the ledger.
state: A commit transitioned between DRAFT / VALIDATING / ATTESTED / PROMOTABLE / DEPLOYED.
policy: A policy contract was updated — useful to notify reviewers.
radar: Conflict Radar produced a HIGH / MEDIUM / LOW overlap. Disabled by default.