初始化项目版本
This commit is contained in:
Axhub Make
143
.agents/skills/claude-api/shared/managed-agents-webhooks.md
Normal file
143
.agents/skills/claude-api/shared/managed-agents-webhooks.md
Normal file
@@ -0,0 +1,143 @@
|
||||
# Managed Agents — Webhooks
|
||||
|
||||
Anthropic can POST to your HTTPS endpoint when a Managed Agents resource changes state — an alternative to holding an SSE stream or polling. Payloads are **thin** (event type + resource IDs only); on receipt, fetch the resource for current state. Every delivery is HMAC-signed.
|
||||
|
||||
> **Direction matters.** This page covers *Anthropic → you* notifications about session/vault state. It does **not** cover *third-party → you* webhooks that *trigger* a session (e.g. a GitHub push handler that calls `sessions.create()`) — that's ordinary application code on your side with no Anthropic-specific wire format.
|
||||
|
||||
---
|
||||
|
||||
## Register an endpoint (Console only)
|
||||
|
||||
Console → **Manage → Webhooks**. There is no programmatic endpoint-management API yet. Secret rotation is supported from the same page.
|
||||
|
||||
| Field | Constraint |
|
||||
|---|---|
|
||||
| URL | HTTPS on port 443, publicly resolvable hostname |
|
||||
| Event types | Subscribe per `data.type` — an endpoint receives only the types it is subscribed to |
|
||||
| Signing secret | `whsec_`-prefixed, 32 bytes, **shown once at creation** — store it |
|
||||
|
||||
---
|
||||
|
||||
## Verify the signature
|
||||
|
||||
Every delivery carries the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. **Use the SDK's `client.beta.webhooks.unwrap()`** — it verifies the signature, rejects payloads more than ~5 minutes old, and returns the parsed event. It reads the `whsec_` secret from `ANTHROPIC_WEBHOOK_SIGNING_KEY`. Pass the headers through untouched; don't hand-roll verification against a single `X-Webhook-Signature` header, which is not the wire format.
|
||||
|
||||
```python
|
||||
import anthropic
|
||||
from flask import Flask, request
|
||||
|
||||
client = anthropic.Anthropic() # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
|
||||
app = Flask(__name__)
|
||||
|
||||
|
||||
@app.route("/webhook", methods=["POST"])
|
||||
def webhook():
|
||||
try:
|
||||
event = client.beta.webhooks.unwrap(
|
||||
request.get_data(as_text=True),
|
||||
headers=dict(request.headers),
|
||||
)
|
||||
except Exception:
|
||||
return "invalid signature", 400
|
||||
|
||||
if event.id in seen_event_ids: # dedupe retries — id is per-event, not per-delivery
|
||||
return "", 204
|
||||
seen_event_ids.add(event.id)
|
||||
|
||||
match event.data.type:
|
||||
case "session.status_idled":
|
||||
session = client.beta.sessions.retrieve(event.data.id)
|
||||
notify_user(session)
|
||||
case "vault_credential.refresh_failed":
|
||||
alert_oncall(event.data.id)
|
||||
|
||||
return "", 204
|
||||
```
|
||||
|
||||
Pass the **raw request body** to `unwrap()` — frameworks that re-serialize JSON (Express `.json()`, Flask `.get_json()`) change the bytes and break the MAC. For other languages, look up the `beta.webhooks.unwrap` binding in the SDK repo (`shared/live-sources.md`); don't hand-roll verification.
|
||||
|
||||
---
|
||||
|
||||
## Payload envelope
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "event",
|
||||
"id": "whe_9d5c1f7e...",
|
||||
"created_at": "2026-03-18T14:05:22Z",
|
||||
"data": {
|
||||
"type": "session.status_idled",
|
||||
"id": "session_01XYZ...",
|
||||
"organization_id": "8a3d2f1e-...",
|
||||
"workspace_id": "c7b0e4d9-..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Switch on `data.type`, fetch the resource by `data.id`, return any **2xx** to acknowledge. `created_at` is when the *event occurred*, not when the delivery was attempted — the `webhook-timestamp` header is the clock for the attempt (see Delivery behavior).
|
||||
|
||||
The top-level `id` is the same value as the `webhook-id` header, and it is per *event*, not per delivery — every retry carries it unchanged. Dedupe on it.
|
||||
|
||||
---
|
||||
|
||||
## Supported `data.type` values
|
||||
|
||||
| `data.type` | Fires when |
|
||||
|---|---|
|
||||
| `session.status_scheduled` | Session created and ready to accept events |
|
||||
| `session.status_run_started` | Agent execution kicked off (every transition to `running`) |
|
||||
| `session.status_idled` | Agent awaiting input (tool approval, custom tool result, or next message) |
|
||||
| `session.status_rescheduled` | A transient error occurred; the session is retrying automatically |
|
||||
| `session.status_terminated` | Session ended — **on completion or on error**, not error-only |
|
||||
| `session.thread_created` | Multiagent: coordinator opened a new subagent thread |
|
||||
| `session.thread_idled` | Multiagent: a subagent thread is waiting for input |
|
||||
| `session.thread_terminated` | A thread ended — child completed its work, or the thread was archived. **Child threads only**; the primary thread's end surfaces as `session.status_terminated` |
|
||||
| `session.outcome_evaluation_ended` | Outcome grader finished one iteration |
|
||||
| `session.updated` | Session properties changed (name, configuration) |
|
||||
| `session.deleted` | Session permanently deleted — no object left to fetch; treat the event itself as final |
|
||||
| `vault.archived` | Vault was archived |
|
||||
| `vault.created` | Vault was created |
|
||||
| `vault.deleted` | Vault was deleted — a `vault_credential.deleted` also fires per underlying credential. No object left to fetch; treat the event itself as final |
|
||||
| `vault_credential.archived` | Credential archived, directly or via vault archival |
|
||||
| `vault_credential.created` | Vault credential was created |
|
||||
| `vault_credential.deleted` | Credential deleted, directly or via vault deletion. No object left to fetch; treat the event itself as final |
|
||||
| `vault_credential.refresh_failed` | MCP OAuth vault credential failed to refresh |
|
||||
| `agent.created` | Agent created |
|
||||
| `agent.updated` | A new agent version was published. Updates that do not create a new version do **not** fire this. |
|
||||
| `agent.archived` | Agent archived |
|
||||
| `agent.deleted` | Agent permanently deleted — no object left to fetch; treat the event itself as final |
|
||||
| `deployment.created` | Scheduled deployment created |
|
||||
| `deployment.updated` | Deployment properties changed (e.g. schedule edited) |
|
||||
| `deployment.paused` | Deployment paused — by request, or automatically when a scheduled run fails with a **non-recoverable** error (archived agent, missing environment). Recoverable failures, including rate limits, do **not** auto-pause. |
|
||||
| `deployment.unpaused` | Deployment unpaused; schedule resumes |
|
||||
| `deployment.archived` | Deployment archived — directly, or as a result of agent archival/deletion |
|
||||
| `deployment.deleted` | Deployment permanently deleted — no object left to fetch; treat the event itself as final |
|
||||
| `deployment_run.started` | A **scheduled** run started. Manual runs do **not** emit `deployment_run.*` events. |
|
||||
| `deployment_run.succeeded` | Scheduled run created its session. Same `data.id` (the run ID) as the run's `.started` event — fetch the deployment run for its `session_id`, then subscribe to the session events to follow the work. |
|
||||
| `deployment_run.failed` | Scheduled run did not create a session. Same `data.id` as the run's `.started` event — fetch the deployment run for `error.type` / `error.message`. |
|
||||
| `environment.created` | Environment created |
|
||||
| `environment.updated` | Environment updated with at least one changed field. A no-op update emits nothing. |
|
||||
| `environment.archived` | Environment archived. Re-archiving an already-archived environment emits nothing. |
|
||||
| `environment.deleted` | Environment deleted, including delete of an already-archived one. No object left to fetch; treat the event itself as final |
|
||||
| `memory_store.created` | Memory store created — by you, or by an Anthropic-operated process that clones one of your stores |
|
||||
| `memory_store.archived` | Memory store archived. Re-archiving an already-archived store emits nothing. |
|
||||
| `memory_store.deleted` | Memory store deleted, including delete of an already-archived one. Cascades to its memories and versions **without** per-memory events — this single event is the signal. No object left to fetch; treat it as final |
|
||||
|
||||
> **There is deliberately no `memory_store.updated`.** Individual memories and memory versions emit no webhook events at all, and neither do an environment's self-hosted work items. If you need per-memory change tracking, poll the memory-versions endpoints (`shared/managed-agents-memory.md`).
|
||||
|
||||
> These are **webhook** `data.type` values — a separate namespace from SSE event types (`session.status_idle`, `span.outcome_evaluation_end`, etc. in `shared/managed-agents-events.md`). Don't reuse SSE constants in webhook handlers.
|
||||
|
||||
---
|
||||
|
||||
## Delivery behavior & pitfalls
|
||||
|
||||
- **Duplicates.** An endpoint can receive the same event more than once; every attempt carries the same top-level `event.id` (= the `webhook-id` header). Dedupe on it.
|
||||
- **Subscription scope.** An event reaches only endpoints subscribed to its type **at the moment it is emitted**. An event emitted while nothing was subscribed is never delivered, and subscribing later does not backfill — subscribe before you need the type.
|
||||
- **No ordering guarantee.** Events are not delivered in occurrence order: `session.status_idled` may arrive before `session.outcome_evaluation_ended`, and a `.deleted` can arrive before the `.archived` for the same resource. **Drive state from the resource you fetch, not from arrival order.**
|
||||
- **Retries: up to three attempts** per endpoint per event, with jittered exponential backoff between 5 and 120 seconds. A response that triggers auto-disable is never retried. **After the last attempt fails the event is dropped** — not queued, and with no signal that it was lost. Webhooks are not a durable log: if you must observe every transition, reconcile by listing or fetching the resource.
|
||||
- **`webhook-timestamp` is re-stamped on every attempt**, so retries don't fail the SDK's five-minute freshness check. It times the *delivery attempt*; use the payload's `created_at` for when the event occurred.
|
||||
- **Auto-disable — three triggers**, each setting `disabled_reason`, all reversible from Console (events emitted while disabled are **not** replayed):
|
||||
- A `3xx` response. Redirects are never followed; disables immediately, on the first attempt. Reason: `auto-disabled: endpoint URL returned a redirect (3xx)`.
|
||||
- The URL resolves to a non-public IP at connect time. Disables immediately. Reason: `auto-disabled: endpoint URL resolved to an invalid address`.
|
||||
- Continuous failure for a sustained period. Reason: `auto-disabled after sustained delivery failures`. **The trigger is duration, not a delivery count** — a single `2xx` resets the window, so one flaky event can't disable the endpoint.
|
||||
- **Thin payload is intentional.** Don't expect `stop_reason`, `outcome_evaluations`, credential secrets, etc. on the webhook body — fetch the resource.
|
||||
Reference in New Issue
Block a user