Event types
Puck emits nine event types. Each event is wrapped in the standard envelope (event_id, event_type, emitted_at, api_version, data) and signed with the per-subscription HMAC secret. See Signature verification for how to validate the X-Puck-Signature header before processing any payload.
Deduplicate on event_id — delivery is at-least-once and the same event may arrive more than once on transient failures.
The standard envelope shape every event uses:
{ "event_id": "018f2e3a-1c47-7a12-b321-aabbccddeeff", "event_type": "<event.type>", "emitted_at": "2026-05-03T14:22:01Z", "api_version": "v1", "data": { ... }}investigation.queued
Fired when an investigation is accepted by the brain and enters the queue. The investigation may not have reached any agent yet — this event signals that the query was valid and processing has begun.
Payload
{ "event_id": "018f2e3a-…", "event_type": "investigation.queued", "emitted_at": "2026-05-03T14:22:00Z", "api_version": "v1", "data": { "investigation_id": "inv_018f2e3a…", "query": "Find unauthorized AI tools running on the engineering fleet", "scope": { "type": "fleet" }, "severity": null, "queued_at": "2026-05-03T14:22:00Z" }}When this fires
Once per investigation, immediately after the NL query is parsed and an investigation record is created. Severity is not yet known at this point; data.severity is null.
Verifying
Every payload includes an X-Puck-Signature header. See Signature verification.
investigation.completed
Fired when an investigation transitions to complete — after the narrative report is stored and all agents have checked in.
Payload
{ "event_id": "018f2e3b-…", "event_type": "investigation.completed", "emitted_at": "2026-05-03T14:35:00Z", "api_version": "v1", "data": { "investigation_id": "inv_018f2e3a…", "query": "Find unauthorized AI tools running on the engineering fleet", "severity": "high", "finding_count": 7, "summary": "3 endpoints running unapproved LLM clients with outbound traffic to api.openai.com", "report_url": "https://puck.acme.com/investigations/inv_018f2e3a…", "completed_at": "2026-05-03T14:35:00Z" }}When this fires
Exactly once per investigation, after the final narrative is written. The payload includes the investigation ID, a short summary, the top-level severity, a finding count, and a link to the full report.
Verifying
See Signature verification — every payload includes an X-Puck-Signature header.
investigation.failed
Fired when an investigation cannot be completed — for example, no agents matched the scope selector, the pathfinder exhausted its turn budget, or a fatal brain error occurred.
Payload
{ "event_id": "018f2e3c-…", "event_type": "investigation.failed", "emitted_at": "2026-05-03T14:23:00Z", "api_version": "v1", "data": { "investigation_id": "inv_018f2e3a…", "query": "Find unauthorized AI tools running on the engineering fleet", "severity": null, "reason": "No agents matched scope selector: tags={team: finance}", "failed_at": "2026-05-03T14:23:00Z" }}When this fires
At most once per investigation. data.reason contains a human-readable explanation. Severity is null; no findings will have been written for this investigation.
Verifying
finding.discovered
Fired each time the brain writes a new finding during an investigation. Findings are written incrementally as agents report results — this event fires before the investigation is complete.
Payload
{ "event_id": "018f2e3d-…", "event_type": "finding.discovered", "emitted_at": "2026-05-03T14:28:00Z", "api_version": "v1", "data": { "finding_id": "fnd_018f2e3d…", "investigation_id": "inv_018f2e3a…", "agent_id": "puck-eng-laptop-47", "title": "Unapproved LLM client: ollama running with outbound traffic to localhost:11434", "severity": "high", "confidence": 0.91, "tags": { "team": "engineering", "layer": "endpoint" }, "discovered_at": "2026-05-03T14:28:00Z" }}When this fires
Once per finding, as soon as the result analyst classifies a result. data.severity is one of low, medium, high, or critical. Subscribe with min_severity: high to receive only high-confidence signals.
Verifying
chain.confirmed
Fired when the hive mind correlator confirms an attack chain — a sequence of findings across multiple endpoints that together form a coherent threat narrative.
Payload
{ "event_id": "018f2e3e-…", "event_type": "chain.confirmed", "emitted_at": "2026-05-03T14:30:00Z", "api_version": "v1", "data": { "chain_id": "chn_018f2e3e…", "investigation_id": "inv_018f2e3a…", "severity": "critical", "finding_ids": ["fnd_018f2e3d…", "fnd_018f2e3f…"], "summary": "Credential exfiltrated from eng-laptop-47 used to authenticate cloud-aws Puck role", "confirmed_at": "2026-05-03T14:30:00Z" }}When this fires
After cross-fleet correlation: one or more finding.discovered events precede this event. data.chain_id groups the chain’s constituent findings. Severity is the highest severity among the chain’s findings.
Verifying
check.graduated
Fired when a finding is promoted to a calibrated detection — a deterministic, repeatable rule the brain can run across the fleet without a full LLM-driven investigation. (The event name retains the “graduated” prefix for backward-compatibility; the product-side feature is called Calibrated Detection.)
Payload
{ "event_id": "018f2e3f-…", "event_type": "check.graduated", "emitted_at": "2026-05-03T15:00:00Z", "api_version": "v1", "data": { "check_id": "chk_018f2e3f…", "finding_id": "fnd_018f2e3d…", "investigation_id": "inv_018f2e3a…", "name": "ollama-process-with-outbound-traffic", "description": "Detects ollama running with active connections outside localhost", "graduated_at": "2026-05-03T15:00:00Z" }}When this fires
After a finding is promoted. Not all findings graduate — only those judged repeatable and high-value. data.check_id identifies the new check in the Graduation library.
Verifying
agent.registered
Fired when an agent sends its first heartbeat — when a newly installed Puck checks in for the first time, or re-registers after a brain restart.
Payload
{ "event_id": "018f2e40-…", "event_type": "agent.registered", "emitted_at": "2026-05-03T09:00:00Z", "api_version": "v1", "data": { "agent_id": "puck-eng-laptop-47", "os": "darwin", "arch": "arm64", "tags": ["endpoint", "team-engineering"], "registered_at": "2026-05-03T09:00:00Z" }}When this fires
On the first accepted heartbeat for a previously unknown agent_id. Use this event to auto-enroll new hosts into your asset inventory or CMDB.
Verifying
agent.disconnected
Fired when the brain has not received a heartbeat from a previously active agent within the lapse window (approximately 3 minutes by default).
Payload
{ "event_id": "018f2e41-…", "event_type": "agent.disconnected", "emitted_at": "2026-05-03T10:03:00Z", "api_version": "v1", "data": { "agent_id": "puck-eng-laptop-47", "os": "darwin", "tags": ["endpoint", "team-engineering"], "last_seen_at": "2026-05-03T10:00:01Z", "disconnected_at": "2026-05-03T10:03:00Z" }}When this fires
When the brain’s liveness checker marks an agent as disconnected. data.last_seen_at is the timestamp of the last accepted heartbeat. Subscribe to this event to alert on unexpected agent loss.
Verifying
graph.edge_drift
Fired when the hive mind detects that a relationship in the finding graph has changed — a trust edge appeared or disappeared compared to the previous investigation baseline.
Payload
{ "event_id": "018f2e42-…", "event_type": "graph.edge_drift", "emitted_at": "2026-05-03T14:32:00Z", "api_version": "v1", "data": { "drift_id": "dft_018f2e42…", "investigation_id": "inv_018f2e3a…", "drift_type": "removed", "edge": { "from": "arn:aws:iam::123456789:role/OrgAccountAccessRole", "to": "arn:aws:iam::987654321:role/AdministratorAccess", "relationship": "sts:AssumeRole" }, "baseline_investigation_id": "inv_018f1a00…", "detected_at": "2026-05-03T14:32:00Z" }}When this fires
After cross-fleet correlation compares the current investigation’s graph against the baseline. data.drift_type is added or removed. A removed edge on a previously-confirmed chain is a strong signal that an attacker has cleaned up or that a legitimate change was made without a change record.