> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cimento.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Hub events

> Every Agent Hub webhook event: findings, rules, settings, MCP servers and attack simulations, with each event's fields and an example.

Every event arrives in the same [envelope](https://docs.cimento.ai/webhooks/receiving-events.md#the-envelope). This page describes `data` for each `type`. The examples are spread over several lines to make them readable.

The [Cimento SDKs](https://docs.cimento.ai/webhooks/verifying-signatures.md#verify-with-a-cimento-sdk) have a type for each event's `data`: see the payload types in the [Go reference](https://pkg.go.dev/github.com/cimento-ai/cimento-sdk/go/webhooks#pkg-types), or narrow on `event.type` in [TypeScript](https://www.npmjs.com/package/@cimento/webhooks).

Agent Hub events name people and things by id. They never include a prompt, a command, file contents or anything else an AI agent's session contained. The one piece of generated text is a finding's `title`.

## Findings

A finding is something a [rule](https://docs.cimento.ai/agent-hub/how-it-works.md) matched.

| `ruleId` | Rule |
| - | - |
| `unapproved_mcp_servers` | Unapproved MCP servers |
| `secrets_and_credentials` | Secrets and credentials |
| `cimento_guard_installed` | Cimento guard installed |
| `acceptable_use` | Acceptable use |
| `customer_data_destinations` | Customer data destinations |

Treat `ruleId` as text that can take new values: Cimento adds rules over time.

> [!NOTE]
>
> `agent_hub.finding.created` is sent only for findings whose rule nudged or blocked the person. A finding from a rule set to watch or fix is not announced, but its later events are still sent. So you can receive a `decided`, `decision_cleared` or `closed` event for a `findingId` you have never seen. Handle those without assuming a `created` came first.

### `agent_hub.finding.created`

A rule that nudges or blocks matched something an AI agent did.

| Field | Type | Description |
| - | - | - |
| `findingId` | string | The finding. The same across all the events about it. |
| `kind` | string | `action` for something an agent did. `exposure` for a condition that lasts until it is fixed, such as a missing guard. |
| `ruleId` | string | The rule that matched. |
| `ruleName` | string | The rule's name. |
| `title` | string | A short description of the finding. |
| `response` | string | What the rule did: `nudge` or `block`. |
| `user.id` | string | The Cimento id of the person whose agent it was. |
| `user.email` | string or `null` | Their email address. `null` when they are no longer in your directory. |

```json theme={null}
{
  "id": "0b1c2c7d-589a-4dad-8eb7-c28d3e4f50c6",
  "type": "agent_hub.finding.created",
  "occurredAt": "2026-11-12T10:14:52.660Z",
  "data": {
    "findingId": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
    "kind": "action",
    "ruleId": "secrets_and_credentials",
    "ruleName": "Secrets and credentials",
    "title": "An API key was passed to a shell command",
    "response": "block",
    "user": {
      "id": "0f9e8d7c-6b5a-4433-9221-100f0e0d0c0b",
      "email": "ada.lovelace@example.com"
    }
  }
}
```

This event arrives a few minutes after the finding, because Cimento waits for the finding's `title` to be written. If the title isn't ready in time, `title` is the rule's name.

### `agent_hub.finding.decided`

An admin recorded a decision on a finding.

| Field | Type | Description |
| - | - | - |
| `findingId` | string | The finding. |
| `decision` | string | What the admin decided. See the table below. |
| `actorId` | string or `null` | The admin who decided. |

| `decision` | The admin said |
| - | - |
| `rotated` | The exposed credential has been rotated. This closes the finding. |
| `false_positive` | The finding was wrong: the rule should not have matched. This closes the finding. |
| `judged_a_key` | A value Cimento had judged not to be a credential is a real key. This opens the finding. |
| `not_a_credential` | A value flagged as a secret is not a credential. This closes the finding. |

More decisions can be added, so handle a value you don't recognize.

```json theme={null}
{
  "id": "1c2d3d8e-69ab-4ebe-9fc8-d39e4f5061d7",
  "type": "agent_hub.finding.decided",
  "occurredAt": "2026-11-12T10:40:03.115Z",
  "data": {
    "findingId": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
    "decision": "rotated",
    "actorId": "3c2b1a0f-9e8d-4766-8554-433c2b1a0f0e"
  }
}
```

### `agent_hub.finding.decision_cleared`

An admin cleared the decision on a finding, reopening it. `data` has the same fields as `agent_hub.finding.decided`, and `decision` is `null`.

```json theme={null}
{
  "id": "2d3e4e9f-7abc-4fcf-8ad9-e4af506172e8",
  "type": "agent_hub.finding.decision_cleared",
  "occurredAt": "2026-11-12T10:55:27.842Z",
  "data": {
    "findingId": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
    "decision": null,
    "actorId": "3c2b1a0f-9e8d-4766-8554-433c2b1a0f0e"
  }
}
```

### `agent_hub.finding.closed`

The condition behind an ongoing finding cleared. This applies to findings whose `kind` is `exposure`: the device reported the control back in place, or the rule was turned off.

| Field | Type | Description |
| - | - | - |
| `findingId` | string | The finding. |
| `ruleId` | string | The rule the finding came from. |

```json theme={null}
{
  "id": "3e4f5fa0-8bcd-4ad0-9bea-f5b0617283f9",
  "type": "agent_hub.finding.closed",
  "occurredAt": "2026-11-12T12:02:41.300Z",
  "data": {
    "findingId": "a0b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
    "ruleId": "cimento_guard_installed"
  }
}
```

## Rules and settings

### `agent_hub.rule.updated`

An admin changed how a rule responds. Saving a rule without changing its response sends nothing.

| Field | Type | Description |
| - | - | - |
| `ruleId` | string | The rule. |
| `response` | string | The rule's new response: `off`, `watch`, `nudge`, `block` or `fix`. Which of these a rule offers depends on the rule. |
| `actorId` | string or `null` | The admin who changed it. |

```json theme={null}
{
  "id": "4f5a60b1-9cde-4be1-8cfb-06c172839400",
  "type": "agent_hub.rule.updated",
  "occurredAt": "2026-11-11T16:08:19.027Z",
  "data": {
    "ruleId": "unapproved_mcp_servers",
    "response": "nudge",
    "actorId": "3c2b1a0f-9e8d-4766-8554-433c2b1a0f0e"
  }
}
```

Turning a rule off closes its open findings, which sends `agent_hub.finding.closed` for each.

### `agent_hub.settings.updated`

An admin changed Agent Hub settings. The event names the settings that changed, never their values. Saving without changing anything sends nothing.

| Field | Type | Description |
| - | - | - |
| `changedKeys` | array of strings | The settings that changed. |
| `actorId` | string or `null` | The admin who changed them. |

| Key | Setting |
| - | - |
| `telemetry.full_content` | Whether [full content](https://docs.cimento.ai/agent-hub/data-collected.md#full-content-capture) is captured |
| `telemetry.retention_days` | How long events and captured content are kept |
| `telemetry.mask` | Whether personal data is masked before it is stored |
| `enforcement.enabled` | Whether rules are enforced. When off, every rule only watches |
| `enforcement.soft_start` | Whether a rule newly set to block nudges for its first week |
| `enforcement.fallback` | Whether a device allows or blocks when its policy is too old to trust |
| `alerts.manager_copy_on_third` | Whether a person's manager is copied on alerts about them |
| `alerts.weekly_summary` | Whether the weekly summary email is sent |

```json theme={null}
{
  "id": "5a6b71c2-adef-4cf2-9d0c-17d283940511",
  "type": "agent_hub.settings.updated",
  "occurredAt": "2026-11-11T16:20:55.489Z",
  "data": {
    "changedKeys": ["enforcement.enabled", "alerts.weekly_summary"],
    "actorId": "3c2b1a0f-9e8d-4766-8554-433c2b1a0f0e"
  }
}
```

## MCP servers

Both events share the same `data`. They say which server gained or lost an approval, not who it was approved for.

| Field | Type | Description |
| - | - | - |
| `mcpServerId` | string | The MCP server. |
| `actorId` | string or `null` | The admin who made the change. |

A server can be approved for everyone, a group, a department or one person, so you can receive more than one `approved` event for the same server. Approving or revoking several servers at once sends one event for each server. Declining a server sends nothing.

### `agent_hub.mcp_server.approved`

An admin approved an MCP server.

```json theme={null}
{
  "id": "6b7c82d3-bef0-4d03-8e1d-28e394a51622",
  "type": "agent_hub.mcp_server.approved",
  "occurredAt": "2026-11-10T13:33:07.914Z",
  "data": {
    "mcpServerId": "b1c2d3e4-f5a6-4b7c-9d8e-0f1a2b3c4d5e",
    "actorId": "3c2b1a0f-9e8d-4766-8554-433c2b1a0f0e"
  }
}
```

### `agent_hub.mcp_server.revoked`

An admin revoked an MCP server's approval.

```json theme={null}
{
  "id": "7c8d93e4-cf01-4e14-9f2e-39f4a5b62733",
  "type": "agent_hub.mcp_server.revoked",
  "occurredAt": "2026-11-12T09:47:38.276Z",
  "data": {
    "mcpServerId": "b1c2d3e4-f5a6-4b7c-9d8e-0f1a2b3c4d5e",
    "actorId": "3c2b1a0f-9e8d-4766-8554-433c2b1a0f0e"
  }
}
```

## Attack simulations

### `agent_hub.simulation.requested`

An admin requested an attack simulation.

| Field | Type | Description |
| - | - | - |
| `requestId` | string | The request. |
| `actorId` | string or `null` | The admin who asked for it. |

```json theme={null}
{
  "id": "8d9ea4f5-d012-4f25-8a3f-4a05b6c73844",
  "type": "agent_hub.simulation.requested",
  "occurredAt": "2026-11-12T15:00:11.052Z",
  "data": {
    "requestId": "c2d3e4f5-a6b7-4c8d-8e9f-1a2b3c4d5e6f",
    "actorId": "3c2b1a0f-9e8d-4766-8554-433c2b1a0f0e"
  }
}
```

### `agent_hub.simulation.completed`

An attack simulation run finished. The event carries counts only: nothing about which attack landed on which agent.

| Field | Type | Description |
| - | - | - |
| `passId` | string | The run. |
| `counts.agents` | number | How many agents the run covered. |
| `counts.saved` | number | How many attack runs were completed and saved. |
| `counts.landed` | number | How many attack goals succeeded across those runs. |
| `counts.notCopyable` | number | How many agents could not be copied for the run. |
| `counts.failed` | number | How many runs failed to complete. |

```json theme={null}
{
  "id": "9eafb506-e123-4a36-9b40-5b16c7d84955",
  "type": "agent_hub.simulation.completed",
  "occurredAt": "2026-11-12T15:38:46.700Z",
  "data": {
    "passId": "d3e4f5a6-b7c8-4d9e-9f0a-2b3c4d5e6f7a",
    "counts": {
      "agents": 24,
      "saved": 46,
      "landed": 3,
      "notCopyable": 1,
      "failed": 2
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.