> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Terminal webhooks and recovery

> **Availability:** The AutoMCP production service is not yet deployed. This page and its examples describe the committed v1 contract for integration planning; requests to the API URL will not succeed until the runtime is released.

Webhook bodies are immutable metadata-only envelopes. Terminal event types include `run.completed`, `run.failed`, and `run.outcome_unknown`; `approval.required` and state-change events are also supported. Bodies contain IDs and state, never conversation text, approval arguments, tool input/output, credentials, or Secrets.

## Webhook envelope

Every delivery uses this immutable JSON body:

```json
{
  "id": "01900000-0000-7000-8000-000000000001",
  "type": "run.completed",
  "version": 1,
  "createdAt": "2026-01-01T00:00:00Z",
  "workspaceId": "01900000-0000-7000-8000-000000000002",
  "appId": "01900000-0000-7000-8000-000000000003",
  "subjectId": "01900000-0000-7000-8000-000000000004",
  "resourceVersion": "7",
  "state": "RUN_STATE_SUCCEEDED"
}
```

`id` is the stable UUID-v7 delivery-deduplication key. Supported `type` values are `run.state_changed`, `run.completed`, `run.failed`, `run.outcome_unknown`, and `approval.required`; `subjectId` is the Run or approval UUID. `state` is the applicable protobuf enum name. The body never contains conversation text, approval arguments, tool input/output, errors with customer content, credentials, or Secrets.

Verify the `AutoMCP-Signature` header over the exact raw body bytes prefixed by the timestamp (`<timestamp>.<exact raw body>`), using the UTF-8 bytes of the returned signing secret and lowercase hexadecimal HMAC-SHA256. The normal header is `AutoMCP-Signature: t=<unix>,v1=<lowercase-hex-hmac-sha256>`. For 24 hours after signing-secret rotation, both digests are serialized in that same header as repeated comma-separated parameters, for example `AutoMCP-Signature: t=1700000000,v1=<old-digest>,v1=<new-digest>`; accept either digest with constant-time comparison. After the 24-hour window, the old secret is destroyed and only the new secret is valid. Check the timestamp replay window before accepting it. `id` is the stable UUID v7 delivery-deduplication key. Delivery is at least once: AutoMCP makes one immediate attempt and at most eight total attempts within 24 hours, with jittered exponential backoff and a 10-second timeout. Timeouts, `429`, and `5xx` responses are retried; other `4xx` responses are not retried automatically. Deduplicate before processing. Manual redelivery preserves the immutable body and uses the current secret set.

Recovery is metadata-only. Operators may inspect recovery records, retry safe cost-evidence or settlement work, redeliver an immutable webhook, and request best-effort cancellation. They cannot read customer payloads, impersonate users, decide approvals, or force an ambiguous external mutation. A lost non-idempotent customer call remains `outcomeUnknown` until the customer verifies its external state.