Webhook

I webhook sono servizi che ospitano la logica di business o chiamano altri servizi. Durante una sessione, i webhook ti consentono di utilizzare i dati estratti dall'elaborazione del linguaggio naturale di Dialogflow CX per generare risposte dinamiche, convalidare i dati raccolti o attivare azioni sul backend.

Un webhook può essere un webhook standard o un webhook flessibile. Con un webhook standard, i campi di richiesta e risposta sono definiti da Dialogflow CX. Con un webhook flessibile, definisci i campi di richiesta e risposta.

Puoi anche accedere al codice di stato HTTP della chiamata webhook utilizzando il parametro di richiesta $request.webhook_status_code.

Webhook standard

Con i webhook standard, utilizzi messaggi di richiesta e risposta definiti da Dialogflow CX. Il messaggio di richiesta fornisce molti dettagli sulla sessione. Ad esempio, sono inclusi la pagina attiva corrente, l'intent corrispondente recente, i valori dei parametri di sessione e le risposte definite dall'agente.

Richiesta webhook standard

Quando viene chiamato un fulfillment con un webhook, Dialogflow CX invia una richiesta webhook POST HTTPS al tuo servizio webhook. Il corpo di questa richiesta è un oggetto JSON WebhookRequest con informazioni sulla sessione.

Alcune integrazioni compilano il campo WebhookRequest.payload con informazioni aggiuntive. Ad esempio, l'integrazione di Dialogflow CX Phone Gateway fornisce l'ID chiamante dell'utente finale.

Per maggiori dettagli, consulta la documentazione di riferimento di WebhookRequest (V3) o WebhookRequest (V3Beta1).

Risposta webhook standard

Dopo aver ricevuto una richiesta, il servizio webhook deve inviare una risposta che soddisfi i seguenti requisiti:

• La risposta deve essere fornita entro il timeout configurato durante la creazione della risorsa webhook.
• La risposta deve avere dimensioni massime pari a 64 KiB.

Per maggiori dettagli, consulta la documentazione di riferimento di WebhookResponse (V3) o WebhookResponse (V3Beta1).

Impostazioni delle risorse webhook standard

La tabella seguente descrive le impostazioni delle risorse webhook per i webhook standard:

X	Elemento
Nome visualizzato	Il nome mostrato nella console per il webhook.
Timeout del webhook	Quando Dialogflow CX invia una richiesta HTTP al tuo servizio webhook, questa impostazione controlla il timeout in secondi per ogni singolo tentativo di richiesta, non per l'intero turno conversazionale. Se un tentativo scade o non va a buon fine con un errore temporaneo, Dialogflow CX riprova automaticamente una volta. Questo nuovo tentativo può comportare un tempo di risposta totale fino al doppio del valore di timeout configurato prima di restituire un errore. Se si verifica un timeout dopo il nuovo tentativo, Dialogflow CX richiama un evento webhook.error.timeout. Per maggiori dettagli, vedi Ritentativi automatici.
Tipo	Imposta Service Directory se utilizzi Service Directory per l'accesso alla rete privata, altrimenti imposta Servizio web generico.
URL webhook	Fornisci l'indirizzo URL del tuo servizio webhook.
Sottotipo	Imposta su Standard.
Webhook specifico per l'ambiente	Puoi fornire webhook specifici per l'ambiente.
Autenticazione	Consulta la sezione Autenticazione.
Certificato CA personalizzato	Viene utilizzato per caricare certificati CA personalizzati.

Webhook flessibili

Con i webhook flessibili, definisci il metodo HTTP della richiesta, i parametri dell'URL della richiesta e i campi dei messaggi di richiesta e risposta. La richiesta può fornire solo i valori dei parametri selezionati e la risposta può fornire solo i valori di override dei parametri. In questo modo, l'interfaccia tra l'agente e il webhook viene semplificata, in quanto raramente è necessario comunicare altro oltre ai valori dei parametri di sessione. Inoltre, semplifica l'implementazione del webhook perché i messaggi di richiesta e risposta contengono solo ciò che ti serve e puoi fornire messaggi webhook unici per vari scenari.

Richiesta webhook flessibile

Quando crei la risorsa webhook per il tuo agente, puoi specificare quanto segue per le richieste webhook:

• Il metodo HTTP utilizzato per le richieste webhook inviate al tuo servizio webhook.
• Valori dei parametri di sessione che Dialogflow CX deve inviare al servizio webhook utilizzando l'URL.
• Valori dei parametri di sessione che Dialogflow CX deve inviare al tuo servizio webhook tramite il corpo JSON della richiesta se scegli POST, PUT o PATCH come metodo.

Per inviare i valori dei parametri di sessione utilizzando l'URL della richiesta o il corpo JSON, utilizza i riferimenti ai parametri. Non devi eseguire l'escape dell'URL del riferimento al parametro né racchiuderlo tra virgolette. In fase di runtime, Dialogflow CX esegue l'escape dell'URL delvalore parametroo in base alle necessità. Un elenco o un valore composito viene fornito come JSON.

Quando utilizzi un riferimento a un parametro nel corpo JSON, devi racchiuderlo tra virgolette, indipendentemente dal tipo di parametro. Se il parametro è in realtà un valore scalare, un elenco o un valore composito numerico, Dialogflow CX rimuove le virgolette quando invia la richiesta in fase di runtime per preservare il tipo di dati del parametro. I tipi scalari stringa rimarranno tra virgolette. Se un valore scalare numerico, un elenco o un valore composito viene fatto riferimento all'interno di un valore stringa (ad esempio: "This is a number: $session.params.size"), il parametro verrà trattato come una stringa ("This is a number: 3").

Ad esempio, puoi fornire i valori dei parametri di sessione fruit e size all'URL della richiesta nel seguente modo:

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

E al corpo JSON della richiesta, come segue:

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

Risposta webhook flessibile

Quando crei la risorsa webhook per il tuo agente, puoi specificare i parametri della sessione che Dialogflow CX deve impostare su campi specifici della risposta webhook in fase di runtime.

La tua risposta deve rispettare i seguenti limiti:

• La risposta deve avvenire entro il timeout configurato durante la creazione della risorsa webhook, altrimenti la richiesta andrà in timeout.
• La risposta deve avere una dimensione massima di 64 KiB.

Per specificare un campo scalare, elenco o composto, utilizza il seguente formato:

$.fully.qualified.path.to.field

Ad esempio, considera la seguente risposta JSON:

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

Per specificare il campo "value", utilizza quanto segue:

$.routes[0].legs[0].distance.value

Impostazioni flessibili delle risorse webhook

La tabella seguente descrive le impostazioni delle risorse webhook per i webhook flessibili.

X	Elemento
Nome visualizzato	Il nome mostrato nella console per il webhook.
Timeout del webhook	Quando Dialogflow CX invia una richiesta HTTP al tuo servizio webhook, questa impostazione controlla il timeout in secondi per ogni singolo tentativo di richiesta, non per l'intero turno conversazionale. Se un tentativo scade o non va a buon fine con un errore temporaneo, Dialogflow CX riprova automaticamente una volta. Questo nuovo tentativo può comportare un tempo di risposta totale fino al doppio del valore di timeout configurato prima di restituire un errore. Se si verifica un timeout dopo il nuovo tentativo, Dialogflow CX richiama un evento webhook.error.timeout. Per maggiori dettagli, vedi Ritentativi automatici.
Tipo	Imposta Service Directory se utilizzi Service Directory per l'accesso alla rete privata, altrimenti imposta Servizio web generico.
URL webhook	Fornisci l'indirizzo URL del tuo servizio webhook, che può includere riferimenti ai parametri di sessione.
Sottotipo	Imposta l'opzione su Flessibile.
Metodo	Imposta il metodo HTTP per la richiesta webhook.
Corpo della richiesta	Fornisci il corpo JSON della richiesta come descritto sopra.
Configurazione della risposta	Fornisci i parametri di sessione che devono essere impostati sui campi di risposta come descritto sopra.
Webhook specifico per l'ambiente	Puoi fornire webhook specifici per l'ambiente
Autenticazione	Consulta la sezione Autenticazione.
Certificato CA personalizzato	Viene utilizzato per caricare certificati CA personalizzati.

Utilizzare un modello personalizzato predefinito

Dialogflow offre modelli personalizzati predefiniti che puoi utilizzare per integrare webhook flessibili con Salesforce CRM.

1. Vai alla scheda Gestisci, seleziona Webhook e poi fai clic su Crea.
2. In Sottotipo, seleziona Flessibile.
3. Fai clic su Configura utilizzando il modello predefinito.
4. Nel menu Tipo di integrazione, seleziona Salesforce.
5. Nel menu Nome API, seleziona un nome API. Il modello compila automaticamente il modulo webhook in base al nome dell'API che scegli.
   1. Configura manualmente i seguenti campi, se applicabile, in base ai tuoi parametri:
      • URL webhook
      • Metodo
      • JSON del corpo della richiesta
      • Configurazione della risposta
   2. I campi OAuth obbligatori verranno evidenziati nella sezione Autenticazione.
6. Fai clic su Salva.

Requisiti del servizio webhook

Il tuo servizio webhook deve soddisfare i seguenti requisiti:

• Gestisci le richieste HTTPS. HTTP non è supportato. Se ospiti il tuo servizio webhook su Google Cloud utilizzando una soluzione di calcolo o serverless computing, consulta la documentazione relativa all'utilizzo di HTTPS. Per altre opzioni di hosting, vedi Ottieni un certificato SSL per il tuo dominio.
• Assicurarsi che l'URL del servizio webhook sia accessibile pubblicamente, a meno che non sia ospitato come risorsa Cloud Run o accessibile come webhook di una directory di servizi.
• Gestisci richieste e risposte come descritto nella sezione webhook standard o webhook flessibile.
• Se il tuo agente non si integra con l'accesso alla rete privata di Service Directory, le chiamate webhook si trovano al di fuori del perimetro di servizio e vengono bloccate quando si abilitano Controlli di servizio VPC. Service Directory supporta endpoint limitati. Per maggiori dettagli, consulta Service Directory.

Autenticazione

Proteggi il tuo servizio webhook in modo che solo tu o il tuo agente Dialogflow CX possiate effettuare richieste. Configura questa impostazione quando crei o modifichi una risorsa webhook. Dialogflow CX supporta i seguenti meccanismi di autenticazione:

X	Elemento
Intestazioni di autenticazione	Per le impostazioni del webhook, puoi specificare coppie chiave-valore di intestazioni HTTP facoltative. Se fornite, Dialogflow CX aggiunge queste intestazioni HTTP alle richieste webhook. È prassi comune fornire una singola coppia con una chiave di authorization. I valori dell'intestazione supportano i riferimenti ai parametri di sessione e l'analisi delle funzioni di sistema come nei messaggi di risposta statici. Se utilizzi una credenziale statica per l'intestazione authorization, ti consigliamo di fornire la credenziale utilizzando Secret Manager.
Autenticazione di base con nome utente e password	Per le impostazioni del webhook, puoi specificare valori facoltativi per nome utente e password di accesso. Se fornita, Dialogflow CX aggiunge un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione ha il formato: "authorization: Basic <base 64 encoding of the string username:password>". Ti consigliamo di fornire il nome utente e la password utilizzando Secret Manager.
OAuth di terze parti	Puoi specificare la configurazione OAuth di terze parti in modo che Dialogflow CX scambi un token di accesso dal sistema OAuth e lo aggiunga all'intestazione HTTP di autorizzazione. È supportato solo il flusso delle credenziali client. Ti consigliamo di fornire il client secret utilizzando Secret Manager.
Token di accesso del service agent	Non più disponibile.
Service account	Puoi utilizzare un service account per l'autenticazione. Può essere utilizzato per accedere ad altre API Google Cloud .
Token ID service agent	Puoi scegliere il token ID nella sezione Autenticazione con agente di servizio, che ti consente di utilizzare il token ID agente di servizio per l'autenticazione. In questo modo puoi accedere alle risorse Cloud Run.
Autenticazione TLS reciproca	Consulta la documentazione relativa all'autenticazione TLS reciproca.

Nota: se sono abilitate più opzioni di autenticazione, quelle con priorità più elevata hanno la precedenza. L'ordine di priorità è il seguente: intestazioni di autenticazione, autenticazione di base, OAuth di terze parti, autenticazione dell'agente di servizio.

Nota: non è consigliabile utilizzare intervalli IP per autenticare le richieste webhook. Se scegli di utilizzare l'IP di origine della richiesta per attivare la connettività al tuo perimetro di rete, consenti le richieste dagli intervalli elencati all'indirizzo https://www.gstatic.com/ipranges/goog.json e nega le connessioni dagli intervalli elencati all'indirizzo https://www.gstatic.com/ipranges/cloud.json (questi sono gli indirizzi di Google che possono essere utilizzati per il deployment di carichi di lavoro di terze parti). Dialogflow non può garantire intervalli IP per le macchine che inviano richieste webhook.

Nota: dopo il 15 agosto 2025, gli agenti esportati non conterranno più credenziali di valori non elaborati per le intestazioni di autenticazione, l'autenticazione di base con nome utente e password o OAuth di terze parti.

OAuth di terze parti

Dialogflow CX raccoglie un token di accesso da un provider OAuth di terze parti e lo aggiunge all'intestazione HTTP di autorizzazione quando effettua richieste webhook.

La tabella seguente descrive le impostazioni delle risorse per OAuth di terze parti:

X	Elemento
ID client	L'ID client da utilizzare per richiedere un token OAuth.
Client secret	Il secret da utilizzare quando richiedi un token OAuth. Ti consigliamo di fornire il client secret utilizzando Secret Manager.
URL endpoint OAuth	L'URL da utilizzare per richiedere un token OAuth.
Ambiti OAuth	Un elenco separato da virgole di ambiti per cui è possibile utilizzare il token OAuth.

Le richieste inviate all'URL dell'endpoint OAuth per ricevere un token non includono le intestazioni delle richieste personalizzate configurate per la richiesta webhook. Puoi trasmettere informazioni personalizzate al server OAuth come parametri all'interno della stringa di query dell'URL dell'endpoint OAuth.

Nota :i token OAuth di terze parti vengono riutilizzati per le richieste webhook utilizzando lo stesso ID client, URL endpoint e ambiti all'interno dello stesso agente Dialogflow CX, a condizione che la richiesta venga effettuata sullo stesso server Dialogflow CX e che il token non sia scaduto. Per ottenere un'alta affidabilità, gli agenti vengono distribuiti su molti server individuali che non condividono le cache dei token OAuth. Quando implementi una soluzione che utilizza token OAuth di terze parti, valuta attentamente l'implementazione di un proxy API per gestire il volume di richieste che l'agente può inviare al tuo provider OAuth di terze parti.

Token ID service agent

Dialogflow CX può generare un token ID utilizzando l'agente di servizio Dialogflow CX. Questo token viene aggiunto all'intestazione HTTP Authorization quando Dialogflow CX chiama un webhook.

Un token ID può essere utilizzato per accedere alle risorse Cloud Run dopo aver concesso il ruolo Cloud Run Invoker (roles/run.invoker) a

service-agent-project-number@gcp-sa-dialogflow.

Se le risorse Cloud Run si trovano nello stesso progetto di risorse, non hai bisogno di un'autorizzazione Identity and Access Management (IAM) aggiuntiva per chiamarle.

Il pubblico utilizzato per generare il token ID è l'intero URL webhook, esclusi i parametri di ricerca. Se utilizzi Cloud Run, assicurati che questo URL sia supportato dai pubblici Cloud Run.

Ad esempio, se l'URL webhook è:

https://myproject.cloudfunctions.net/my-function/method1?query=value

Il seguente URL deve essere presente nei segmenti di pubblico personalizzati:

https://myproject.cloudfunctions.net/my-function/method1

Qualsiasi webhook può anche convalidare facoltativamente il token utilizzando le librerie client Google o librerie open source come la libreria di autenticazione Google per Node.js.

Se il webhook è ospitato su Cloud Run e viene eseguito l'accesso tramite un bilanciatore del carico, aggiungi l'URL del bilanciatore del carico come segmento di pubblico personalizzato a Cloud Run. Per saperne di più sui segmenti di pubblico personalizzati, vedi Impostare segmenti di pubblico personalizzati per i servizi.

Service account

I service account possono essere utilizzati per autenticare le richieste webhook a qualsiasi API di Google che le supporta.

Se non l'hai ancora fatto, crea un account di servizio.

Poiché i service account sono entità, possono accedere alle risorse del tuo progetto concedendo loro un ruolo, proprio come qualsiasi altra entità. L'email del account di servizio viene utilizzata per generare un token di accesso che viene inviato nell'intestazione Authorization della richiesta webhook.

Per configurare il webhook in modo che utilizzi i service account, devi disporre delle seguenti autorizzazioni:

• roles/iam.serviceAccountUser

Per generare token, l'agente di servizio Dialogflow deve disporre delle seguenti autorizzazioni:

• roles/iam.serviceAccountTokenCreator

Il account di servizio deve disporre anche delle autorizzazioni per accedere al servizio che ospita il webhook.

Nota: se stai tentando di utilizzare service account in più progetti, assicurati che i criteri dell'organizzazione lo supportino. Entrambe le autorizzazioni devono essere concesse nel progetto che contiene il service account.

Autenticazione di Secret Manager

Se utilizzi intestazioni di autenticazione, autenticazione di base con nome utente e password o OAuth di terze parti, puoi archiviare le credenziali come secret utilizzando Secret Manager. Di seguito sono riportati i passaggi necessari per autenticare il webhook utilizzando i secret:

1. Crea il secret se non ne hai uno.
2. Concedi al service agent Dialogflow il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) per il nuovo secret.
3. Copia le credenziali negli appunti.
4. Aggiungi una nuova versione del secret al tuo secret e incolla le tue credenziali come valore del secret:
   • Se utilizzi le intestazioni di autenticazione, inserisci Bearer <YOUR_CREDENTIAL>.
   • Se utilizzi l'autenticazione di base con nome utente e password, inserisci <YOUR_USERNAME>:<YOUR_PASSWORD>.
   • Ometti qualsiasi carattere di nuova riga alla fine.
5. Copia il nome della versione del secret che hai aggiunto. Il formato del nome è projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>.
6. Apri la schermata di modifica del webhook.
7. Configura le impostazioni di autenticazione:
   • Se utilizzi le intestazioni di autenticazione, crea una nuova intestazione della richiesta di versione del secret. Inserisci "Authorization" nel campo Chiave e incolla il nome della versione del secret nel campo Versione del secret.
   • Per l'autenticazione di base con nome utente e password, fai clic su Versione del secret in Autenticazione di base e incolla il nome della versione del secret nel campo Versione del secret.
   • Se utilizzi OAuth di terze parti, fai clic su Versione secret in OAuth di terze parti e incolla il nome della versione secret nel campo Versione secret.
8. Fai clic su Salva.

Nota: supportiamo solo i secret di Secret Manager globali. Non supportiamo i secret regionali.

Verifica del certificato HTTPS

Per impostazione predefinita, Dialogflow CX utilizza l'archivio di attendibilità predefinito di Google per verificare i certificati HTTPS. Se intendi utilizzare certificati non riconosciuti dall'archivio di attendibilità predefinito di Google per il tuo server HTTPS, ad esempio certificati autofirmati o certificati radice personalizzati, consulta Certificati CA personalizzati.

Webhook specifici per l'ambiente

Se utilizzi gli ambienti per isolare la produzione dallo sviluppo, puoi configurare i webhook in modo che siano specifici per l'ambiente. Puoi fornire URL e impostazioni di autenticazione specifici per l'ambiente per ogni risorsa webhook.

Questa configurazione ti consente di sviluppare e testare in sicurezza gli aggiornamenti del codice webhook prima di eseguirne il deployment in produzione.

Creare o modificare le risorse webhook

Dopo aver eseguito un servizio webhook, crea una risorsa webhook nell'agente che includa informazioni di connettività e autenticazione. Puoi modificare le impostazioni delle risorse webhook in qualsiasi momento.

Per creare o modificare una risorsa webhook:

Console

1. Apri la console Dialogflow CX.
2. Vai al tuo progetto.
3. Seleziona l'agente.
4. Fai clic sulla scheda Gestisci.
5. Fai clic su Webhook.
6. Fai clic su Crea o seleziona un webhook esistente da modificare.
7. Configura le impostazioni della risorsa webhook standard o le impostazioni della risorsa webhook flessibile.
8. Fai clic su Salva.

API

Per informazioni sulla creazione di una risorsa webhook, consulta il metodo create per il tipo Webhook. Per informazioni sulla modifica di una risorsa webhook (ad eccezione delle impostazioni specifiche per l'ambiente), consulta il metodo patch o update per il tipo Webhook. Vai al riferimento API Webhook

Seleziona un protocollo e una versione per il riferimento webhook:

Protocollo	V3	V3beta1
REST	Risorsa webhook	Risorsa webhook
RPC	Interfaccia webhook	Interfaccia webhook
C++	WebhooksClient	Non disponibile
C#	WebhooksClient	Non disponibile
Vai	WebhooksClient	Non disponibile
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	Non disponibile	Non disponibile
Python	WebhooksClient	WebhooksClient
Ruby	Non disponibile	Non disponibile

Close

Per informazioni sulla modifica delle impostazioni specifiche dell'ambiente per un webhook, vedi il metodo patch o update per il tipo Environment. Vai al riferimento API Environment

Seleziona un protocollo e una versione per il riferimento all'ambiente:

Protocollo	V3	V3beta1
REST	Risorsa ambiente	Risorsa ambiente
RPC	Interfaccia dell'ambiente	Interfaccia dell'ambiente
C++	EnvironmentsClient	Non disponibile
C#	EnvironmentsClient	Non disponibile
Vai	EnvironmentsClient	Non disponibile
Java	EnvironmentsClient	EnvironmentsClient
Node.js	EnvironmentsClient	EnvironmentsClient
PHP	Non disponibile	Non disponibile
Python	EnvironmentsClient	EnvironmentsClient
Ruby	Non disponibile	Non disponibile

Close

Errori webhook

Se il servizio webhook rileva un errore durante la gestione di una richiesta webhook, il codice webhook deve restituire uno dei seguenti codici di stato HTTP:

• 400: Richiesta errata
• 401: Non autorizzato
• 403: Vietato
• 404: Non trovato
• 500: Errore del server
• 503: Servizio non disponibile

Dialogflow CX richiama un errore o un timeout del webhook evento integrato e continua l'elaborazione come di consueto nelle seguenti situazioni di errore:

• Il timeout della risposta è stato superato.
• Viene ricevuto un codice di stato di errore.
• La risposta non è valida.
• Il servizio webhook non è disponibile.

Se la chiamata al servizio webhook è stata attivata da una chiamata all'API detect intent, il campo queryResult.webhookStatuses nella risposta detect intent contiene le informazioni sullo stato del webhook.

Nuovi tentativi automatici

Dialogflow CX ritenta automaticamente le richieste in caso di determinati errori webhook per migliorare la robustezza. I tentativi automatici sono abilitati per impostazione predefinita e non possono essere disattivati.

Dialogflow CX esegue un solo tentativo per gli errori temporanei, come timeout delle richieste, interruzioni delle connessioni di rete e codici di stato HTTP nell'intervallo 5xx (ad esempio 500 Server fault o 503 Service unavailable). Gli errori del client terminale, come il codice di stato HTTP 404 Not found, non vengono ritentati.

Latenza cumulativa e budget per il timeout

Poiché Dialogflow CX ritenta una volta gli errori temporanei, un endpoint webhook che non risponde può comportare un tempo di risposta cumulativo fino al doppio del valore di timeout configurato prima che Dialogflow CX restituisca un errore. Ad esempio, con l'impostazione di timeout predefinita di 5 secondi, un endpoint che non risponde va in timeout dopo 5 secondi al primo tentativo e dopo altri 5 secondi al tentativo di ripetizione. Il risultato è una latenza totale di circa 10 secondi prima che Dialogflow CX richiami i gestori di errori, ad esempio un gestore di eventi webhook.error.timeout o un gestore di eventi sys.no-match-default.

Se la tua architettura ha limiti di latenza upstream rigorosi (ad esempio sistemi di telefonia o IVR che terminano le chiamate dopo un intervallo di timeout di 10 secondi), prevedi entrambi i tentativi impostando il timeout del webhook a metà dell'intervallo consentito (ad esempio, tra 2,5 e 4 secondi).

Best practice per i tentativi

Per gestire i nuovi tentativi in modo efficace nel tuo servizio webhook:

• Implementa l'idempotenza o la deduplicazione delle richieste nella logica del servizio webhook per elaborare in modo sicuro le richieste duplicate.
• Se l'operazione webhook richiede più tempo del timeout configurato, restituisci una risposta immediata con codice di stato HTTP 200 OK con un messaggio di riserva ed elabora l'attività a lunga esecuzione in modo asincrono.

Utilizzo di Cloud Run

Attenzione: questa sezione descrive come utilizzare le risorse Cloud Run sicure per i webhook Dialogflow CX. È consigliabile mantenere le risorse sicure. Se scegli di autenticarti con nome utente e password basati su URL o intestazioni HTTP, devi consentire l'accesso non autenticato alla risorsa Cloud Run.

Dialogflow CX si integra con Cloud Run, in modo da poter creare un webhook serverless sicuro. Se crei una risorsa Cloud Run che si trova nello stesso progetto dell'agente, seleziona Autenticazione agente di servizio e poi Token ID nella configurazione dell'autenticazione, in modo che l'agente possa chiamare in modo sicuro il webhook.

Devi configurare manualmente questa integrazione nelle seguenti due situazioni:

1. Per il progetto dell'agente deve esistere il service agent Dialogflow CX service account con il seguente indirizzo:

   service-agent-project-number@gcp-sa-dialogflow.

   Questo account di servizio speciale e la chiave associata vengono normalmente creati automaticamente quando crei il primo agente per un progetto. Se il tuo agente è stato creato prima del 1° novembre 2020, puoi attivare la creazione di questo account di servizio speciale:
   1. Crea un nuovo agente per il progetto.
   2. Esegui questo comando:

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

2. Se la funzione webhook si trova in un progetto diverso dall'agente, devi fornire il ruolo IAM Cloud Run Invoker o Cloud Functions Invoker al account di servizio Dialogflow CX Service Agent nel progetto di risorse Cloud Run.

A questo punto, seleziona Service Agent Auth > ID Token nella sezione Configurazione autenticazione.

Utilizzo di webhook containerizzati e del framework Go ezcx

Per implementare un webhook containerizzato utilizzando Go, consulta il framework Go ezcx. Questo framework semplifica molti dei passaggi necessari per creare un webhook.

Utilizzo di Cloud Run con traffico solo interno

Nota: l'utilizzo di Cloud Run al di fuori del perimetro dei Controlli di servizio VPC del progetto dell'agente Dialogflow CX per i webhook non è supportato.

Puoi utilizzare le risorse Cloud Run configurate per accettare il traffico interno dalle reti Virtual Private Cloud (VPC) nello stesso progetto o nello stesso perimetro dei Controlli di servizio VPC come webhook, a condizione che l'agente si trovi nello stesso progetto o nello stesso perimetro dei Controlli di servizio VPC.

Utilizzo di Service Directory per l'accesso alla rete privata

Dialogflow CX si integra con l'accesso alla rete privata di Service Directory, in modo da potersi connettere alle destinazioni webhook all'interno della tua rete VPC. In questo modo, il traffico rimane all'interno della rete Google Cloud e vengono applicati IAM e i Controlli di servizio VPC.

Per configurare un webhook che ha come target una rete privata:

1. Segui la configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint Service Directory.

   Nota: Dialogflow CX memorizza nella cache le informazioni di Service Directory per 90 secondi. Ciò significa che quando aggiorni l'endpoint Service Directory, la modifica richiede 90 secondi.

2. Per il progetto dell'agente deve esistere il service agent Dialogflow CX service account con il seguente indirizzo:

   service-agent-project-number@gcp-sa-dialogflow.

   Concedi i seguenti ruoli al service account service agent Dialogflow CX nel progetto in cui si trova Service Directory:

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   Inoltre, se Service Directory si trova in un progetto diverso dal tuo agente Dialogflow CX, devi anche concedere il ruolo servicedirectory.viewer all'account del service agent Dialogflow CX nel progetto che ospita l'agente Dialogflow CX.

3. Specifica il servizio Service Directory, l'URL e qualsiasi informazione di autenticazione facoltativa quando crei il webhook.

   Console

   

   API

   Visualizza il campo serviceDirectory per il tipo Webhook. Vai al riferimento API Webhook

   Seleziona un protocollo e una versione per il riferimento webhook:

   Protocollo	V3	V3beta1
   REST	Risorsa webhook	Risorsa webhook
   RPC	Interfaccia webhook	Interfaccia webhook
   C++	WebhooksClient	Non disponibile
   C#	WebhooksClient	Non disponibile
   Vai	WebhooksClient	Non disponibile
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	Non disponibile	Non disponibile
   Python	WebhooksClient	WebhooksClient
   Ruby	Non disponibile	Non disponibile

   Close

Per risolvere i problemi, puoi configurare un controllo di uptime privato per verificare che Service Directory sia configurato correttamente.

Esempi e risoluzione dei problemi

Per saperne di più, consulta la guida illustrativa sui webhook.