The findings feed

A stream of what happens to findings, for the tools that enforce: a gateway, a policy engine, an identity system.

What this is. Provantix reports. When a finding opens, gets worse, is acknowledged, is resolved or is followed up, it writes one event. Your tool reads that event and decides what to do with it.

What this is not. Provantix does not sit in an agent's execution path, does not block anything, and does not tell your tool what to enforce. If your gateway slows an agent down because a finding rose to High, that is your gateway's rule. Nothing here is a control.

In the product

Findings page corresponding to conditions exposed through the feed

Product capture, 15–16 November 2026. Open the image for full size. Counts and dates are examples from the captured workspace.

This is the human review screen for findings that the feed reports. The screenshot does not show a feed subscription or delivery acknowledgement. Use the event and acknowledgement contracts below to integrate an external tool.

What an event holds

An event names the finding and links back to it. It never carries record content, finding text, a person's name or a payload.

{
  "schema": "provantix.finding_event.v1",
  "event_id": "fev_3f9a1c0b7d2e4a5b6c7d8e9f",
  "sequence": 412,
  "type": "severity_rise",
  "occurred_at": "2026-11-12T12:05:00.000Z",
  "finding": { "id": "fnd_…", "kind": "unclaimed_destination_change", "subject": "scp_…", "severity": "high", "status": "open" },
  "previous_severity": "medium",
  "actor": "system",
  "run_id": "run_…",
  "link": "https://app.example.com/findings?kind=unclaimed_destination_change&subject=scp_…"
}
Type When
finding_opened A check found something new.
finding_recurred A finding that had been resolved came back.
severity_rise The severity went up. previous_severity says from what.
finding_acknowledged A person acknowledged it. actor is person, never a name.
finding_reopened A person reopened it.
finding_resolved A run found it no longer applies, or a person resolved it.
finding_stale It stopped being refreshed and was set aside.
follow_up_outcome A follow-up closed. outcome says what happened.

The schema name carries a version. A field is added without changing it; a field is never removed or changed in meaning without a new version.

Two ways to read it

Pull. GET /v1/feed/events?after=<sequence>&limit=<n> with Authorization: Bearer <pull credential>. You get events, next_cursor and has_more. Keep next_cursor and ask for events after it next time. Reading changes nothing: the same request returns the same events. Reads are limited to 120 a minute per subscription (answer 429).

Webhook. Give a subscription an https address. Provantix posts each event there, one at a time and in order.

Make a subscription

An administrator creates it (POST /v1/feed/subscriptions with name, and optionally target_url, event_types and min_severity). The answer shows the pull credential and, for a webhook, the signing secret once. They cannot be shown again. The credential is stored as a hash and the secret encrypted. Revoking a subscription wipes both.

A subscription can ask for only some event types and only findings at or above a severity. Events it does not want are skipped without stalling anything.

The webhook address must be https and must not resolve to a private or internal address.

Verify a webhook

Each delivery carries:

  • x-provantix-timestamp: seconds since the epoch.
  • x-provantix-signature: v1= and the hex HMAC-SHA256 of <timestamp>.<raw body> under your secret.
  • x-provantix-event-id and x-provantix-delivery-attempt.

Check the signature over the exact bytes received, compare in constant time, and refuse a timestamp more than five minutes from now. The timestamp is part of the signed text, so it cannot be changed, and a captured delivery cannot be replayed later.

Delivery is at least once, and can arrive out of order

  • Duplicates. The same event can arrive twice (a retry after a timeout you did answer). Keep the event_ids you have applied and ignore a repeat.
  • Order. Events are sent in order, but a pull and a webhook can both run. For each finding, the event with the highest sequence wins; an older one arriving late must not undo a newer state.
  • Failures. If your endpoint does not answer 2xx, delivery stops at that event, so nothing is skipped, and is retried after 1, 2, 4 … minutes, never more than an hour apart. The failure, its status and the next attempt show in the subscription's list and delivery log.

Report back what you did

A consumer can tell Provantix what it did about a finding. This is optional, and it is your tool's own report: Provantix did not do it and does not show that it happened. It is kept beside the finding, shown as "reported by ", and it never changes the finding, its status or its evidence.

POST /v1/feed/acknowledgements        with the subscription's own credential (the one it reads the feed with)
{ "acknowledgement_id": "gw-2026-11-12-001",     your own id for this report: what makes a retry safe
  "finding_id": "fnd_...",
  "outcome": "observed" | "escalated" | "approval_requested" | "denied" | "credential_revoked",
  "occurred_at": "2026-11-12T11:57:00Z",         when you did it
  "detail": "revoked at the gateway",            optional, up to 300 characters
  "evidence_ref": "gw://decisions/12" }          optional: a pointer into your own system, never content
  • Signed when the subscription has a webhook secret. Sign the exact bytes you send the same way a delivery is signed (x-provantix-signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<body>")> and x-provantix-timestamp, within five minutes). A subscription with no webhook secret is authenticated by its credential alone, and each report says which it was.
  • Safe to retry. Send the same acknowledgement_id again and the answer is duplicate, with the original receipt time kept. The same id with different content is refused (409), so a retry can never rewrite what you reported.
  • Order does not matter. A report that arrives late, with an earlier time than one already held, sits beside it. Nothing is overwritten. Both your time and our receipt time are kept.
  • No report means unknown. A finding no tool has reported on shows "none reported", which is not the same as nothing being done.
  • What it is not. It is not evidence that Provantix blocked, denied or revoked anything, and it is not proof that your tool did. If your tool can also record its verdicts as evidence, see Control decisions.

Reading is limited to the same 120 requests a minute as the feed. Admins see the reports on the Findings page, under each finding, when a tool is connected.

acknowledge() in the reference consumer sends one, signed when you give it the secret.

A reference consumer

ledger/scripts/findings-feed-consumer.mjs does the checks above: verifyWebhook (signature and timestamp), createConsumer (duplicates, late events, latest state per finding) and pullAll (paging with a cursor). It enforces nothing; its onChange is where your rule goes. The same code runs against the feed in the test suite.

Examples of what a consumer does

  • A gateway keeps a set of agents with an open High finding and routes their next high-risk call to a person.
  • A policy engine treats finding_resolved as the signal to lift a temporary restriction it applied itself.
  • An identity system opens a ticket to review an agent's credentials on finding_opened of a kind about missing ownership.

In each case the decision is the consumer's. A finding is an observation, and its meaning is stated on its own page.