webhooks changedmanaged-agents/webhooks
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+23added
Lines−23removed
From line
18
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 18, old and new numbered
/
from line 18
1818
1919<Tabs>
2020 <Tab title="Session events">
21 Some of these events are named differently from the matching events on the session's [event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). For example, the stream's `session.status_idle` and `session.status_running` correspond to the `session.status_idled` and `session.status_run_started` webhook events.
21 Some of these events are named differently from the matching events on the session’s [event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). For example, the stream’s `session.status_idle` and `session.status_running` correspond to the `session.status_idled` and `session.status_run_started` webhook events.
2222
2323 | Event | Trigger |
2424 | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
from line 27
2727 | `session.budget_reached` | The session reached its [budget](https://platform.claude.com/docs/en/managed-agents/budgets) and paused. Fires at most once for each budget value you set; changing the budget arms it again. |
2828 | `session.status_rescheduled` | A transient error occurred and the session is retrying automatically. |
2929 | `session.status_terminated` | The session terminated, either because of an unrecoverable error or because it was archived. |
30 | `session.thread_created` | New [multiagent thread](https://platform.claude.com/docs/en/managed-agents/session-threads) opened: an additional agent called by the agent that the session runs is starting work, or the session's [advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) is being consulted. It also fires for each thread of a [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs#a-runs-threads), and so do the other two thread events in this table. |
30 | `session.thread_created` | New [multiagent thread](https://platform.claude.com/docs/en/managed-agents/session-threads) opened: an additional agent called by the agent that the session runs is starting work, or the session’s [advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) is being consulted. It also fires for each thread of a [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs#a-runs-threads), and so do the other two thread events in this table. |
3131 | `session.thread_idled` | An agent in a [multiagent interaction](https://platform.claude.com/docs/en/managed-agents/session-threads) is waiting for input. |
32 | `session.thread_terminated` | A [multiagent thread](https://platform.claude.com/docs/en/managed-agents/session-threads) terminated, either because the thread was archived or because it exhausted its retries. A subagent that finishes its work goes `idle`, not `terminated` (an advisor thread terminates once its consultation completes, and a workflow run's threads terminate when the server archives them, by the end of the run). Fires for child threads only; the primary thread's end, including archiving the whole session, surfaces only as `session.status_terminated`. |
32 | `session.thread_terminated` | A [multiagent thread](https://platform.claude.com/docs/en/managed-agents/session-threads) terminated, either because the thread was archived or because it exhausted its retries. A subagent that finishes its work goes `idle`, not `terminated` (an advisor thread terminates once its consultation completes, and a workflow run’s threads terminate when the server archives them, by the end of the run). Fires for child threads only; the primary thread’s end, including archiving the whole session, surfaces only as `session.status_terminated`. |
3333 | `session.outcome_evaluation_ended` | [Outcome evaluation](https://platform.claude.com/docs/en/managed-agents/define-outcomes) for a single iteration completed. |
3434 | `session.updated` | Session properties changed (for example, its name or configuration was updated). |
3535 | `session.deleted` | Session permanently deleted. There is no object left to fetch, so treat the event itself as final. |
from line 48
4848 </Tab>
4949
5050 <Tab title="Agent events">
51 These events track the lifecycle of the agent resources in your workspace, and are distinct from the agent events delivered on a session's event stream.
51 These events track the lifecycle of the agent resources in your workspace, and are distinct from the agent events delivered on a session’s event stream.
5252
5353 | Event | Trigger |
5454 | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
from line 63
6363 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
6464 | `deployment.created` | [Scheduled deployment](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments) created. |
6565 | `deployment.updated` | Deployment properties changed (for example, its schedule was updated). |
66 | `deployment.paused` | Deployment paused, either by request or automatically when a scheduled run fails with an unrecoverable error, such as an archived subagent or an archived environment. Recoverable failures, including rate limits, don't pause the deployment. See [Failure behavior](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments#failure-behavior). |
66 | `deployment.paused` | Deployment paused, either by request or automatically when a scheduled run fails with an unrecoverable error, such as an archived subagent or an archived environment. Recoverable failures, including rate limits, don’t pause the deployment. See [Failure behavior](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments#failure-behavior). |
6767 | `deployment.unpaused` | Deployment unpaused, resuming its schedule. |
6868 | `deployment.archived` | Deployment archived, either directly or because its agent was archived. If the agent is deleted instead, a scheduled deployment is archived at its next scheduled run; a deployment without a schedule is not archived automatically. |
6969 | `deployment.deleted` | Deployment permanently deleted. There is no object left to fetch, so treat the event itself as final. |
from line 73
7373 | Event | Trigger |
7474 | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7575 | `deployment_run.started` | A scheduled run started. Only scheduled runs emit `deployment_run` events; [manual runs](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments#trigger-a-manual-run) do not. |
76 | `deployment_run.succeeded` | A scheduled run created its session. The event carries the same `data.id` (the run ID) as the run's `deployment_run.started` event. To follow the session's work, subscribe to its session events (the **Session events** tab), or fetch the [deployment run](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments#deployment-runs) for its `session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`). |
77 | `deployment_run.failed` | A scheduled run did not create a session. The event carries the same `data.id` as the run's `deployment_run.started` event. Fetch the [deployment run](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments#deployment-runs) for the error details. |
76 | `deployment_run.succeeded` | A scheduled run created its session. The event carries the same `data.id` (the run ID) as the run’s `deployment_run.started` event. To follow the session’s work, subscribe to its session events (the **Session events** tab), or fetch the [deployment run](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments#deployment-runs) for its `session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`). |
77 | `deployment_run.failed` | A scheduled run did not create a session. The event carries the same `data.id` as the run’s `deployment_run.started` event. Fetch the [deployment run](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments#deployment-runs) for the error details. |
7878 </Tab>
7979
8080 <Tab title="Environment events">
from line 85
8585 | `environment.archived` | Environment archived. Re-archiving an already-archived environment emits nothing. |
8686 | `environment.deleted` | Environment deleted, including delete of an already-archived environment. There is no object left to fetch, so treat the event itself as final. |
8787
88 An environment's [work items](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes) emit no webhook events.
88 An environment’s [work items](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes) emit no webhook events.
8989 </Tab>
9090
9191 <Tab title="Memory store events">
from line 106
106106A webhook endpoint consists of:
107107
108108* **URL:** Must be HTTPS on port 443 with a publicly resolvable hostname.
109* **Event types:** The list of `data.type` values this endpoint receives. An endpoint only receives events it's subscribed to.
110* **Signing secret:** A 32-byte `whsec_`-prefixed secret generated at creation. It's shown only once, so store it securely to verify webhook deliveries.
109* **Event types:** The list of `data.type` values this endpoint receives. An endpoint only receives events it’s subscribed to.
110* **Signing secret:** A 32-byte `whsec_`-prefixed secret generated at creation. It’s shown only once, so store it securely to verify webhook deliveries.
111111
112112## Verify the signature
113113
114Every delivery carries the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. Use the SDK's `unwrap()` (csharp, go: `Unwrap()`) helper to verify the signature and parse the event in one step. It throws if the signature is invalid or the payload is more than 5 minutes old.
114Every delivery carries the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. Use the SDK’s `unwrap()` (csharp, go: `Unwrap()`) helper to verify the signature and parse the event in one step. It throws if the signature is invalid or the payload is more than 5 minutes old.
115115
116116Set `ANTHROPIC_WEBHOOK_SIGNING_KEY` to the `whsec_`-prefixed secret shown at endpoint creation.
117117
from line 419
419419 ```
420420</CodeGroup>
421421
422The top-level `event.id` is unique for each event, not for each delivery. If you receive the same `event.id` twice, it's a retry and you can discard it.
422The top-level `event.id` is unique for each event, not for each delivery. If you receive the same `event.id` twice, it’s a retry and you can discard it.
423423
424424## Delivery behavior
425425
426426* **Duplicates:** An endpoint can receive the same event more than once, and every attempt delivers the same top-level `event.id` (the same value as the `webhook-id` header). Deduplicate on it.
427427
428* **Subscription scope:** An event is delivered only to endpoints subscribed to its type at the moment it's emitted. An event emitted while no endpoint is subscribed to its type is never delivered, and subscribing later doesn't backfill it, so subscribe to an event type before you need it.
428* **Subscription scope:** An event is delivered only to endpoints subscribed to its type at the moment it’s emitted. An event emitted while no endpoint is subscribed to its type is never delivered, and subscribing later doesn’t backfill it, so subscribe to an event type before you need it.
429429
430* **Ordering:** Events aren't guaranteed to be delivered in the order they occurred: `session.status_idled` might arrive before `session.outcome_evaluation_ended` even if the outcome was produced first, and a `.deleted` event can arrive before the `.archived` event for the same resource. Drive your state from the resource you fetch, not from the order events arrive in.
430* **Ordering:** Events aren’t guaranteed to be delivered in the order they occurred: `session.status_idled` might arrive before `session.outcome_evaluation_ended` even if the outcome was produced first, and a `.deleted` event can arrive before the `.archived` event for the same resource. Drive your state from the resource you fetch, not from the order events arrive in.
431431
432* **Retries:** For each endpoint and event, Anthropic makes up to three delivery attempts (a response that triggers auto-disable, described later in this section, is never retried) with jittered exponential backoff between 5 and 120 seconds. Every attempt delivers the same `event.id`. After the last attempt fails, the event is dropped: it isn't queued for later delivery and there's no signal that it was lost. Webhooks aren't a durable log, so if you need to observe every transition, reconcile by listing or fetching the resource through the API.
432* **Retries:** For each endpoint and event, Anthropic makes up to three delivery attempts (a response that triggers auto-disable, described later in this section, is never retried) with jittered exponential backoff between 5 and 120 seconds. Every attempt delivers the same `event.id`. After the last attempt fails, the event is dropped: it isn’t queued for later delivery and there’s no signal that it was lost. Webhooks aren’t a durable log, so if you need to observe every transition, reconcile by listing or fetching the resource through the API.
433433
434* **Timestamps:** The `webhook-timestamp` header is stamped when a delivery attempt is signed and is regenerated on every retry, so retries aren't rejected by the SDK's freshness check. It's the clock for the delivery attempt, not for the event: use the event payload's `created_at` (java, php: `createdAt`; csharp, go: `CreatedAt`) for when the event occurred.
434* **Timestamps:** The `webhook-timestamp` header is stamped when a delivery attempt is signed and is regenerated on every retry, so retries aren’t rejected by the SDK’s freshness check. It’s the clock for the delivery attempt, not for the event: use the event payload’s `created_at` (java, php: `createdAt`; csharp, go: `CreatedAt`) for when the event occurred.
435435
436436* **Auto-disable:** An endpoint is automatically set to `disabled` with a machine-readable `disabled_reason` in three cases:
437437
438438 * The endpoint returns a `3xx` response. Redirects are never followed; this disables the endpoint immediately, on the first attempt, with the reason `auto-disabled: endpoint URL returned a redirect (3xx)`. If your endpoint moves, update the URL in Console and re-enable the endpoint.
439 * The endpoint's URL resolves to a non-public IP address when Anthropic connects. This disables the endpoint immediately, with the reason `auto-disabled: endpoint URL resolved to an invalid address`.
440 * Deliveries to the endpoint fail continuously for a sustained period, with the reason `auto-disabled after sustained delivery failures`. The trigger is how long the endpoint has been failing without interruption, not a delivery count. A single `2xx` resets the window, so one event that fails intermittently can't disable the endpoint.
439 * The endpoint’s URL resolves to a non-public IP address when Anthropic connects. This disables the endpoint immediately, with the reason `auto-disabled: endpoint URL resolved to an invalid address`.
440 * Deliveries to the endpoint fail continuously for a sustained period, with the reason `auto-disabled after sustained delivery failures`. The trigger is how long the endpoint has been failing without interruption, not a delivery count. A single `2xx` resets the window, so one event that fails intermittently can’t disable the endpoint.
441441
442 All three are reversible: re-enable the endpoint in Console after you resolve the issue. Events emitted while the endpoint was disabled aren't replayed.
442 All three are reversible: re-enable the endpoint in Console after you resolve the issue. Events emitted while the endpoint was disabled aren’t replayed.
443443
No line in this hunk matches that.