Webhooks and the JSON API: get vendor state changes into your own tools

Two ways to take CertReports data out of the browser: the public JSON API, which returns a vendor’s dated states with sources, and webhooks, which push change events for the vendors you follow into your own systems the moment they are published. Webhooks are part of Buyer Team; the API is available on every plan with limits by plan. This note documents both, with the payload shapes, the signature scheme, the retry policy and the vocabulary you must keep intact downstream.

100 / day

Free API calls per IP

No key required

1,000 / day

Buyer Pro, per key

Create keys on the account page

10,000 / day

Buyer Team, per key

Plus webhooks

The JSON API

The vendor endpoint is the same data the vendor page renders: one row per framework with the state, the as-of date, the source and the evidence URL, and the accuracy disclaimer in every response. Keys are created on the account page and carry the plan’s daily limit; the response includes the remaining calls for the day.

Example response

{ "vendor": { "slug": "datadog", "name": "Datadog" }, "states": [ { "framework": "soc-2", "state": "vendor_stated", "as_of": "2026-09-12", "source": "trust_center", "evidence_url": "https://..." }, { "framework": "fedramp", "state": "verified_registry", "as_of": "2026-09-17", "source": "fedramp_marketplace", "evidence_url": "https://..." } ], "disclaimer": "States describe public evidence, not certification." }

Webhook deliveries

CertReports POSTs a JSON body to each active https endpoint whenever a published change event touches a vendor on your watchlist. Deliveries run with the alert digest and retry up to five times on a non-2xx response or a ten-second timeout. Each delivery has a unique id for de-duplication and a signature computed with your endpoint secret, which is shown once when the endpoint is created.

Verifying the signature

1. Read the raw request body as bytes; do not re-serialise the JSON.
2. Split the header on commas to get t and v1.
3. Compute HMAC-SHA256 over the string "<t>.<raw body>" with the endpoint secret.
4. Compare with v1 using a constant-time comparison, and reject timestamps older than five minutes.

Node example

const [t, v1] = header.split(",").map((p) => p.split("=")[1]); const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"); const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Payload

{ "id": "…", "type": "change_event", "created_at": "…", "data": { "event_id": "…", "kind": "attestation_expired", "title": "…", "summary": "…", "occurred_at": "…", "vendor": { "slug": "…", "name": "…", "url": "https://certreports.com/vendors/…/security" }, "framework": "iso-27001", "from_state": "vendor_stated", "to_state": "expired" } }

Retry and failure policy

Event kinds you will see

• attestation_added: a new public evidence row for a framework.
• attestation_renewed: a newer date or period on an existing row.
• attestation_expired: a printed expiry, usage end date or twelve-month window passed.
• attestation_removed: the source no longer shows the row.
• legal_doc_changed: DPA, BAA, subprocessor list or security.txt changed.

Keep the vocabulary intact

States use the same vocabulary as the site: verified_registry, verified_auditor, vendor_stated, third_party, expired, no_public_evidence, not_applicable. Never map no_public_evidence to "non-compliant" in your own tooling; it means nothing public was found at the last check. Keep the as_of date with every state you store, because the state is only meaningful with it.