> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.fortresstech.io/api-reference/webhooks/on-agent-state-changed/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.fortresstech.io/_mcp/server.

# agent.state_changed

POST 

Delivered when staff enable or disable the document-review agent. Generic: scope says whether the switch applies globally, to one organization, to one property or to one household, and each scope carries only its own id, every other id being null (GLOBAL: all null; ORGANIZATION: organizationId only; PROPERTY: propertyId only; HOUSEHOLD: householdId only). MVP: only the global kill switch is sent (scope GLOBAL), delivered once per property subscription with organizationId, propertyId and householdId all null. ORGANIZATION, PROPERTY and HOUSEHOLD are reserved for later and are not sent in the MVP.

Fortress POSTs this payload to the URL configured for your subscription. See
[Webhooks](/webhooks/webhooks) for delivery, signing and retry rules, and the
[event page](/webhooks/webhook-events/webhooks/agent-state-changed) for when it does and does not fire.


Reference: https://developer.fortresstech.io/api-reference/webhooks/on-agent-state-changed

## Request

### Payload

- `eventId` (string, required) — Unique identifier for this event. Stable across delivery attempts, so consumers must dedupe on this value. Also sent as the X-Fortress-Event-Id header.
- `eventType` (enum, required) — What happened, in resource.action form. Also sent as the X-Fortress-Event-Type header. New values are added over time.
  - Allowed values: `agent.state_changed`
- `occurredAt` (datetime, required) — ISO-8601 UTC timestamp of when the event occurred, not when it was delivered. A retried delivery carries the original occurredAt.
- `data` (AgentStateChangedData, required) — Event payload. The shape is determined by eventType.

## Types

### AgentStateChangedData

Payload of an agent.state_changed event. A generic agent switch: scope says what it applies to, and each scope carries only its own id; every other id is null. GLOBAL: all ids null. ORGANIZATION: organizationId only. PROPERTY: propertyId only. HOUSEHOLD: householdId only. MVP: only GLOBAL is sent, delivered once per property subscription with all ids null. ORGANIZATION, PROPERTY and HOUSEHOLD are reserved for later and are not sent in the MVP.

- `organizationId` (string, required, nullable) — The organization the switch applies to. Set only when scope is ORGANIZATION; null otherwise.
- `propertyId` (string, required, nullable) — The property the switch applies to. Set only when scope is PROPERTY; null otherwise.
- `householdId` (string, required, nullable) — The household the switch applies to. Set only when scope is HOUSEHOLD; null otherwise.
- `agentKey` (string, required) — The agent the switch applies to.
- `scope` (enum, required) — What the switch applies to; only its own id is set. MVP sends GLOBAL only. ORGANIZATION, PROPERTY and HOUSEHOLD are reserved for later.
  - Allowed values: `GLOBAL`, `ORGANIZATION`, `PROPERTY`, `HOUSEHOLD`
- `fromEnabled` (boolean, required) — Whether the agent was enabled before the change.
- `toEnabled` (boolean, required) — Whether the agent is enabled after the change.
- `actorId` (string, required) — The staff user who changed the state.
- `reason` (string, optional, nullable) — Why the state changed, when staff gave a reason.