---
title: Iscriviti ai webhook
url: https://platform.claude.com/docs/it/managed-agents/webhooks
description: Ricevi notifiche quando si verificano eventi importanti senza dover effettuare polling.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
Le sessioni sono interazioni di lunga durata. Mentre la maggior parte delle interazioni in tempo reale avviene tramite lo [stream di eventi SSE](https://platform.claude.com/docs/it/managed-agents/events-and-streaming), i webhook ti notificano i principali cambiamenti di stato.
Gli eventi webhook restituiscono il `type` e l'`id` dell'evento, non l'oggetto completo. Quando ricevi un evento webhook, devi recuperare l'oggetto direttamente con una chiamata `GET`. Questo evita di consegnare dati obsoleti durante i tentativi ripetuti e mantiene ogni consegna di piccole dimensioni.
## Tipi di evento supportati
Alcuni di questi eventi hanno nomi diversi rispetto agli eventi corrispondenti nello [stream di eventi](https://platform.claude.com/docs/it/managed-agents/events-and-streaming) della sessione. Ad esempio, `session.status_idle` e `session.status_running` dello stream corrispondono agli eventi webhook `session.status_idled` e `session.status_run_started`.
| Evento | Attivazione |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session.status_run_started` | L'esecuzione dell'agente è iniziata. Si attiva a ogni transizione dello stato della sessione a `running`. |
| `session.status_idled` | L'agente è in attesa di input, ad esempio l'approvazione di un permesso per uno strumento o un nuovo messaggio dell'utente. |
| `session.budget_reached` | La sessione ha raggiunto il suo [budget](https://platform.claude.com/docs/it/managed-agents/budgets) ed è stata messa in pausa. Si attiva al massimo una volta per ogni valore di budget impostato; modificare il budget lo riattiva. |
| `session.status_rescheduled` | Si è verificato un errore transitorio e la sessione sta ritentando automaticamente. |
| `session.status_terminated` | La sessione è terminata, a causa di un errore irrecuperabile oppure perché è stata archiviata. |
| `session.thread_created` | È stato aperto un nuovo [thread multiagente](https://platform.claude.com/docs/it/managed-agents/session-threads): un agente aggiuntivo chiamato dall'agente eseguito dalla sessione sta iniziando a lavorare, oppure viene consultato l'[advisor](https://platform.claude.com/docs/it/managed-agents/multiagent-orchestration#give-the-session-an-advisor) della sessione. Si attiva anche per ogni thread di un'[esecuzione di workflow](https://platform.claude.com/docs/it/managed-agents/workflow-runs#a-runs-threads), così come gli altri due eventi di thread in questa tabella. |
| `session.thread_idled` | Un agente in un'[interazione multiagente](https://platform.claude.com/docs/it/managed-agents/session-threads) è in attesa di input. |
| `session.thread_terminated` | Un [thread multiagente](https://platform.claude.com/docs/it/managed-agents/session-threads) è terminato, perché il thread è stato archiviato oppure perché ha esaurito i suoi tentativi. Un subagente che completa il proprio lavoro passa a `idle`, non a `terminated` (un thread advisor termina una volta completata la consultazione, e i thread di un'esecuzione di workflow terminano quando il server li archivia, entro la fine dell'esecuzione). Si attiva solo per i thread figli; la fine del thread principale, inclusa l'archiviazione dell'intera sessione, emerge solo come `session.status_terminated`. |
| `session.outcome_evaluation_ended` | La [valutazione del risultato](https://platform.claude.com/docs/it/managed-agents/define-outcomes) per una singola iterazione è stata completata. |
| `session.updated` | Le proprietà della sessione sono cambiate (ad esempio, il suo nome o la sua configurazione sono stati aggiornati). |
| `session.deleted` | Sessione eliminata definitivamente. Non rimane alcun oggetto da recuperare, quindi considera l'evento stesso come definitivo. |
| Evento | Attivazione |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vault.created` | Vault creato. |
| `vault.archived` | Vault archiviato. Viene emesso anche un evento `vault_credential.archived` per ogni credenziale sottostante. |
| `vault.deleted` | Vault eliminato. Viene emesso anche un evento `vault_credential.deleted` per ogni credenziale sottostante. Non rimane alcun oggetto da recuperare, quindi considera l'evento stesso come definitivo. |
| `vault_credential.created` | Credenziale creata. |
| `vault_credential.archived` | Credenziale archiviata, direttamente o come conseguenza dell'archiviazione del vault. |
| `vault_credential.deleted` | Credenziale eliminata, direttamente o come conseguenza dell'eliminazione del vault. Non rimane alcun oggetto da recuperare, quindi considera l'evento stesso come definitivo. |
| `vault_credential.refresh_failed` | Una credenziale `mcp_oauth` non può essere aggiornata (refresh token non valido o errore irrecuperabile dal server OAuth). |
Questi eventi tracciano il ciclo di vita delle risorse agente nel tuo workspace e sono distinti dagli eventi dell'agente consegnati nello stream di eventi di una sessione.
| Evento | Attivazione |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent.created` | Agente creato. |
| `agent.updated` | È stata pubblicata una [nuova versione dell'agente](https://platform.claude.com/docs/it/managed-agents/agent-setup#update-an-agent). Gli aggiornamenti che non creano una nuova versione non attivano questo evento. |
| `agent.archived` | Agente archiviato. |
| `agent.deleted` | Agente eliminato definitivamente. Non rimane alcun oggetto da recuperare, quindi considera l'evento stesso come definitivo. |
| Evento | Attivazione |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deployment.created` | [Deployment pianificato](https://platform.claude.com/docs/it/managed-agents/scheduled-deployments) creato. |
| `deployment.updated` | Le proprietà del deployment sono cambiate (ad esempio, la sua pianificazione è stata aggiornata). |
| `deployment.paused` | Deployment messo in pausa, su richiesta oppure automaticamente quando un'esecuzione pianificata fallisce con un errore irrecuperabile, come un subagente archiviato o un ambiente archiviato. I fallimenti recuperabili, inclusi i limiti di velocità, non mettono in pausa il deployment. Consulta [Comportamento in caso di errore](https://platform.claude.com/docs/it/managed-agents/scheduled-deployments#failure-behavior). |
| `deployment.unpaused` | Deployment riattivato, con ripresa della sua pianificazione. |
| `deployment.archived` | Deployment archiviato, direttamente oppure perché il suo agente è stato archiviato. Se invece l'agente viene eliminato, un deployment pianificato viene archiviato alla sua successiva esecuzione pianificata; un deployment senza pianificazione non viene archiviato automaticamente. |
| `deployment.deleted` | Deployment eliminato definitivamente. Non rimane alcun oggetto da recuperare, quindi considera l'evento stesso come definitivo. |
| Evento | Attivazione |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deployment_run.started` | È iniziata un'esecuzione pianificata. Solo le esecuzioni pianificate emettono eventi `deployment_run`; le [esecuzioni manuali](https://platform.claude.com/docs/it/managed-agents/scheduled-deployments#trigger-a-manual-run) no. |
| `deployment_run.succeeded` | Un'esecuzione pianificata ha creato la sua sessione. L'evento contiene lo stesso `data.id` (l'ID dell'esecuzione) dell'evento `deployment_run.started` dell'esecuzione. Per seguire il lavoro della sessione, iscriviti ai suoi eventi di sessione (la scheda Eventi di sessione), oppure recupera l'[esecuzione del deployment](https://platform.claude.com/docs/it/managed-agents/scheduled-deployments#deployment-runs) per ottenere il suo `session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`). |
| `deployment_run.failed` | Un'esecuzione pianificata non ha creato una sessione. L'evento contiene lo stesso `data.id` dell'evento `deployment_run.started` dell'esecuzione. Recupera l'[esecuzione del deployment](https://platform.claude.com/docs/it/managed-agents/scheduled-deployments#deployment-runs) per i dettagli dell'errore. |
| Evento | Attivazione |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment.created` | Ambiente creato. |
| `environment.updated` | Ambiente aggiornato con almeno un campo modificato. Un aggiornamento senza modifiche non emette nulla. |
| `environment.archived` | Ambiente archiviato. Archiviare nuovamente un ambiente già archiviato non emette nulla. |
| `environment.deleted` | Ambiente eliminato, inclusa l'eliminazione di un ambiente già archiviato. Non rimane alcun oggetto da recuperare, quindi considera l'evento stesso come definitivo. |
Gli [elementi di lavoro](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes) di un ambiente non emettono eventi webhook.
| Evento | Attivazione |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memory_store.created` | Memory store creato, da te oppure da un processo gestito da Anthropic che clona uno dei tuoi store esistenti. |
| `memory_store.archived` | Memory store archiviato. Archiviare nuovamente uno store già archiviato non emette nulla. |
| `memory_store.deleted` | Memory store eliminato, inclusa l'eliminazione di uno store già archiviato. L'eliminazione di uno store si propaga a cascata alle sue memorie e alle versioni delle memorie senza emettere eventi per singola memoria; il singolo evento `memory_store.deleted` è il segnale. Non rimane alcun oggetto da recuperare, quindi considera l'evento stesso come definitivo. |
Le singole [memorie](https://platform.claude.com/docs/it/managed-agents/memory) e le versioni delle memorie non emettono eventi webhook.
## Registra un endpoint
Nella Claude Console, vai alla pagina [Webhooks](https://platform.claude.com/settings/workspaces/default/webhooks) (`platform.claude.com/settings/workspaces/default/webhooks`). Ogni endpoint appartiene a un workspace. Seleziona il workspace desiderato nel selettore dei workspace nella barra laterale.
Un endpoint webhook è composto da:
* **URL:** Deve essere HTTPS sulla porta 443 con un hostname risolvibile pubblicamente.
* **Tipi di evento:** L'elenco dei valori `data.type` che questo endpoint riceve. Un endpoint riceve solo gli eventi a cui è iscritto.
* **Segreto di firma:** Un segreto di 32 byte con prefisso `whsec_` generato al momento della creazione. Viene mostrato una sola volta, quindi conservalo in modo sicuro per verificare le consegne dei webhook.
## Verifica la firma
Ogni consegna include gli header `webhook-id`, `webhook-timestamp` e `webhook-signature`. Usa l'helper `unwrap()` (csharp, go: `Unwrap()`) dell'SDK per verificare la firma e analizzare l'evento in un unico passaggio. Genera un'eccezione se la firma non è valida o se il payload ha più di 5 minuti.
Imposta `ANTHROPIC_WEBHOOK_SIGNING_KEY` sul segreto con prefisso `whsec_` mostrato alla creazione dell'endpoint.
```python Python
from flask import Flask, request
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
app = Flask(__name__)
@app.route("/webhook", methods=["POST"])
def webhook():
try:
# unwrap() solleva un'eccezione se la firma non è valida o il payload è scaduto
event = client.beta.webhooks.unwrap(
request.get_data(as_text=True),
headers=dict(request.headers),
)
except Exception:
return "invalid signature", 400
if event.data.type == "session.status_idled":
print("session idled:", event.data.id)
# gestisci gli altri tipi di evento
return "", 200
```
```typescript TypeScript
import express from "express";
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
const app = express();
// IMPORTANTE: usa express.raw(), non express.json(). La firma è calcolata sui byte grezzi.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
let event;
try {
// unwrap() genera un'eccezione se la firma non è valida o il payload è scaduto
event = client.beta.webhooks.unwrap(req.body.toString("utf8"), {
headers: req.headers as Record
});
} catch {
return res.status(400).send("invalid signature");
}
switch (event.data.type) {
case "session.status_idled":
console.log("session idled:", event.data.id);
break;
// gestisci gli altri tipi di evento
}
res.sendStatus(200);
});
```
```csharp C#
using Anthropic;
var client = new AnthropicClient(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
var app = WebApplication.Create(args);
app.MapPost("/webhook", async (HttpRequest request) =>
{
using var reader = new StreamReader(request.Body);
var body = await reader.ReadToEndAsync();
var headers = request.Headers.ToDictionary(header => header.Key, header => header.Value.ToString());
UnwrapWebhookEvent webhookEvent;
try
{
// Unwrap() genera un'eccezione se la firma non è valida o il payload è obsoleto
webhookEvent = client.Beta.Webhooks.Unwrap(body, headers);
}
catch
{
return Results.BadRequest("invalid signature");
}
if (webhookEvent.Data.TryPickSessionStatusIdled(out var idled))
{
Console.WriteLine($"session idled: {idled.ID}");
}
// gestisci gli altri tipi di evento
return Results.Ok();
});
```
```go Go
package main
import (
"fmt"
"io"
"net/http"
"github.com/anthropics/anthropic-sdk-go"
)
var client = anthropic.NewClient() // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
func webhook(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "could not read body", http.StatusBadRequest)
return
}
// Unwrap restituisce un errore se la firma non è valida o il payload è obsoleto
event, err := client.Beta.Webhooks.Unwrap(body, r.Header)
if err != nil {
http.Error(w, "invalid signature", http.StatusBadRequest)
return
}
switch event.Data.Type {
case "session.status_idled":
fmt.Println("session idled:", event.Data.ID)
// gestisci gli altri tipi di evento
}
w.WriteHeader(http.StatusOK)
}
func main() {
http.HandleFunc("/webhook", webhook)
}
```
```java Java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.UnwrapWebhookParams;
import com.anthropic.core.http.Headers;
import com.sun.net.httpserver.HttpServer;
// legge ANTHROPIC_WEBHOOK_SIGNING_KEY dall'ambiente
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
void main() throws Exception {
var server = HttpServer.create(new InetSocketAddress(8000), 0);
server.createContext("/webhook", exchange -> {
var body = new String(exchange.getRequestBody().readAllBytes());
var headers = Headers.builder();
exchange.getRequestHeaders().forEach(headers::put);
try {
// unwrap() genera un'eccezione se la firma non è valida o il payload è scaduto
var event = client.beta().webhooks().unwrap(
UnwrapWebhookParams.builder()
.body(body)
.headers(headers.build())
.build());
event.data().sessionStatusIdled().ifPresent(idled ->
IO.println("session idled: " + idled.id()));
// gestisci gli altri tipi di evento
exchange.sendResponseHeaders(200, -1);
} catch (Exception _) {
exchange.sendResponseHeaders(400, -1);
}
exchange.close();
});
}
```
```php PHP
use Anthropic\Client;
use Anthropic\Core\Exceptions\WebhookException;
$client = new Client(); // reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
$body = file_get_contents('php://input');
$headers = getallheaders();
try {
// unwrap() genera un'eccezione se la firma non è valida o il payload è obsoleto
$event = $client->beta->webhooks->unwrap($body, headers: $headers);
} catch (WebhookException) {
http_response_code(400);
exit('invalid signature');
}
match ($event->data->type) {
'session.status_idled' => print "session idled: {$event->data->id}\n",
// gestisci gli altri tipi di evento
default => null,
};
http_response_code(200);
```
```ruby Ruby
require "sinatra"
require "anthropic"
client = Anthropic::Client.new # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env
post "/webhook" do
headers = request.env
.select { |key, _| key.start_with?("HTTP_") }
.transform_keys { it.delete_prefix("HTTP_").downcase.tr("_", "-") }
begin
# unwrap solleva un'eccezione se la firma non è valida o il payload è scaduto
event = client.beta.webhooks.unwrap(request.body.read, headers: headers)
rescue StandardError
halt 400, "invalid signature"
end
if event.data.type == :"session.status_idled"
puts "session idled: #{event.data.id}"
end
# gestisci gli altri tipi di evento
status 200
end
```
## Gestisci un evento
Analizza il corpo, esegui uno switch su `data.type` e recupera la risorsa tramite ID. Restituisci un qualsiasi `2xx` per confermare la ricezione. Qualsiasi altra risposta viene conteggiata a sfavore dell'endpoint: un `3xx` lo disabilita immediatamente (i reindirizzamenti non vengono mai seguiti), mentre gli altri errori vengono ritentati; consulta [Comportamento di consegna](https://platform.claude.com/docs/it/managed-agents/webhooks#delivery-behavior) per le regole sui tentativi ripetuti e sulla disabilitazione automatica.
Ogni payload di evento ha la stessa struttura, che include il tipo di evento, l'identificatore e il timestamp del momento in cui l'evento si è verificato.
```json
{
"type": "event",
"id": "whe_9d5c1f7e...",
"created_at": "2026-03-18T14:05:22Z",
"data": {
"type": "session.status_idled",
"id": "sesn_01XYZ...",
"organization_id": "8a3d2f1e-...",
"workspace_id": "c7b0e4d9-..."
}
}
```
```python Python
if event.data.type == "session.status_idled":
session = client.beta.sessions.retrieve(event.data.id)
notify_user(session)
return "", 204
```
```typescript TypeScript
if (event.data.type === "session.status_idled") {
const session = await client.beta.sessions.retrieve(event.data.id);
notifyUser(session);
}
res.sendStatus(204);
```
```csharp C#
if (webhookEvent.Data.TryPickSessionStatusIdled(out var idled))
{
var session = await client.Beta.Sessions.Retrieve(idled.ID);
NotifyUser(session);
}
return Results.StatusCode(204);
```
```go Go
if event.Data.Type == "session.status_idled" {
session, err := client.Beta.Sessions.Get(r.Context(), event.Data.ID, anthropic.BetaSessionGetParams{})
if err != nil {
panic(err)
}
notifyUser(session)
}
w.WriteHeader(http.StatusNoContent)
```
```java Java
event.data().sessionStatusIdled().ifPresent(idled -> {
var session = client.beta().sessions().retrieve(idled.id());
notifyUser(session);
});
exchange.sendResponseHeaders(204, -1);
```
```php PHP
if ($event->data->type === 'session.status_idled') {
$session = $client->beta->sessions->retrieve($event->data->id);
notifyUser($session);
}
http_response_code(204);
```
```ruby Ruby
if event.data.type == :"session.status_idled"
session = client.beta.sessions.retrieve(event.data.id)
notify_user(session)
end
status 204
```
L'`event.id` di primo livello è univoco per evento, non per consegna. Se ricevi lo stesso `event.id` due volte, si tratta di un tentativo ripetuto e puoi scartarlo.
## Comportamento di consegna
* **Duplicati:** Un endpoint può ricevere lo stesso evento più di una volta, e ogni tentativo consegna lo stesso `event.id` di primo livello (lo stesso valore dell'header `webhook-id`). Esegui la deduplicazione su di esso.
* **Ambito dell'iscrizione:** Un evento viene consegnato solo agli endpoint iscritti al suo tipo nel momento in cui viene emesso. Un evento emesso mentre nessun endpoint è iscritto al suo tipo non viene mai consegnato, e iscriversi in seguito non lo recupera retroattivamente, quindi iscriviti a un tipo di evento prima di averne bisogno.
* **L'ordine non è garantito.** Gli eventi non vengono consegnati nell'ordine in cui si sono verificati: `session.status_idled` potrebbe arrivare prima di `session.outcome_evaluation_ended` anche se il risultato è stato prodotto per primo, e un evento `.deleted` può arrivare prima dell'evento `.archived` per la stessa risorsa. Basa il tuo stato sulla risorsa che recuperi, non sull'ordine di arrivo degli eventi.
* **Tentativi ripetuti:** Per ogni endpoint ed evento, Anthropic effettua fino a tre tentativi di consegna (una risposta che attiva la disabilitazione automatica, descritta più avanti in questa sezione, non viene mai ritentata) con backoff esponenziale con jitter tra 5 e 120 secondi. Ogni tentativo consegna lo stesso `event.id`. Dopo il fallimento dell'ultimo tentativo, l'evento viene scartato: non viene messo in coda per una consegna successiva e non c'è alcun segnale che sia andato perso. I webhook non sono un log durevole, quindi se hai bisogno di osservare ogni transizione, esegui una riconciliazione elencando o recuperando la risorsa tramite l'API.
* **Timestamp:** L'header `webhook-timestamp` viene impostato quando un tentativo di consegna viene firmato e viene rigenerato a ogni tentativo ripetuto, quindi i tentativi ripetuti non vengono rifiutati dal controllo di freschezza dell'SDK. È l'orologio del tentativo di consegna, non dell'evento: usa il `created_at` (java, php: `createdAt`; csharp, go: `CreatedAt`) del payload dell'evento per sapere quando l'evento si è verificato.
* **Disabilitazione automatica:** Un endpoint viene impostato automaticamente su `disabled` con un `disabled_reason` leggibile dalla macchina in tre casi:
* L'endpoint restituisce una risposta `3xx`. I reindirizzamenti non vengono mai seguiti; questo disabilita l'endpoint immediatamente, al primo tentativo, con il motivo `auto-disabled: endpoint URL returned a redirect (3xx)`. Se il tuo endpoint si sposta, aggiorna l'URL nella Console e riabilita l'endpoint.
* L'URL dell'endpoint si risolve in un indirizzo IP non pubblico quando Anthropic si connette. Questo disabilita l'endpoint immediatamente, con il motivo `auto-disabled: endpoint URL resolved to an invalid address`.
* Le consegne all'endpoint falliscono continuamente per un periodo prolungato, con il motivo `auto-disabled after sustained delivery failures`. L'attivazione dipende da quanto tempo l'endpoint ha continuato a fallire senza interruzioni, non da un numero di consegne. Un singolo `2xx` azzera la finestra, quindi un singolo evento instabile non può disabilitare l'endpoint.
Tutti e tre i casi sono reversibili: riabilita l'endpoint nella Console dopo aver risolto il problema. Gli eventi emessi mentre l'endpoint era disabilitato non vengono riprodotti.