Webhook

I webhook sono servizi che ospitano la tua logica di business o chiamano altri servizi. Durante una sessione, i webhook ti consentono di utilizzare l'estrazione dati 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 i 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 HTTPS POST 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 avvenire entro il timeout configurato durante la creazione della risorsa webhook.
• La risposta deve avere dimensioni massime di 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 di conversazione. 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 un nuovo tentativo, Dialogflow CX richiama un evento webhook.error.timeout. Per maggiori dettagli, consulta Tentativi automatici.
Tipo	Imposta su Service Directory se utilizzi Service Directory per l'accesso alla rete privata, altrimenti imposta su Servizio web generico.
URL webhook	Fornisci l'indirizzo URL del tuo servizio webhook.
Sottotipo	Impostalo 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 valori parametro selezionati e la risposta può fornire solo valori di override dei parametri. In questo modo, l'interfaccia tra l'agente e il webhook viene semplificata, poiché raramente è necessario comunicare qualcosa di diverso dai valori dei parametri di sessione. Inoltre, semplifica l'implementazione del webhook perché i messaggi di richiesta e risposta contengono solo ciò di cui hai bisogno e puoi fornire messaggi webhook univoci per vari scenari.

Richiesta webhook flessibile

Quando crei la risorsa webhook per l'agente, puoi specificare quanto segue per le richieste webhook:

• Il metodo HTTP utilizzato per le richieste di 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 è necessario eseguire l'escape dell'URL del riferimento al parametro o racchiuderlo tra virgolette. In fase di runtime, Dialogflow CX esegue l'escape dell'URL del valore parametro in base alle esigenze. Un elenco o un valore composito viene fornito come JSON.

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

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

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 l'agente, puoi specificare i parametri di sessione che Dialogflow CX deve impostare su campi specifici della risposta del webhook in fase di runtime.

La tua risposta deve rispettare le seguenti limitazioni:

• La risposta deve essere inviata entro il timeout configurato durante la creazione della risorsa webhook, altrimenti la richiesta scadrà.
• La dimensione della risposta deve essere al massimo di 64 KiB.

Per specificare un campo scalare, elenco o composito, 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 di conversazione. 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 un nuovo tentativo, Dialogflow CX richiama un evento webhook.error.timeout. Per maggiori dettagli, consulta Tentativi automatici.
Tipo	Imposta su Service Directory se utilizzi Service Directory per l'accesso alla rete privata, altrimenti imposta su Servizio web generico.
URL webhook	Fornisci l'indirizzo URL del tuo servizio webhook, che può includere riferimenti ai parametri di sessione.
Sottotipo	Impostalo 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.

Utilizza 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 un 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 del webhook in base al nome dell'API che scegli.
   1. Se applicabile, configura manualmente i seguenti campi 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 per i servizi webhook

Il servizio webhook deve soddisfare i seguenti requisiti:

• Gestire le richieste HTTPS. HTTP non è supportato. Se ospiti il tuo servizio webhook su Google Cloud utilizzando una soluzione di computing o serverless computing, consulta la documentazione per la pubblicazione con HTTPS. Per altre opzioni di hosting, consulta Ottieni un certificato SSL per il tuo dominio.
• Assicurati che l'URL del servizio webhook sia accessibile pubblicamente, a meno che non sia ospitato come risorsa Cloud Run o non sia accessibile come webhook di Service Directory.
• Gestisci le richieste e le risposte come descritto nella sezione Webhook standard o Webhook flessibile.
• Se l'agente non si integra con l'accesso alla rete privata di Service Directory, le chiamate webhook si trovano all'esterno del perimetro di servizio e vengono bloccate quando attivi i Controlli di servizio VPC. Service Directory supporta endpoint limitati; per i 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 opzione 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 facoltative per l'intestazione HTTP. Se fornite, Dialogflow CX aggiunge queste intestazioni HTTP alle richieste del webhook. È prassi comune fornire una singola coppia con una chiave 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 i valori facoltativi di nome utente e password di accesso. Se fornita, Dialogflow CX aggiunge un'intestazione HTTP di autorizzazione alle richieste del webhook. Questa intestazione ha il seguente 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 nell'intestazione HTTP di autorizzazione. È supportato solo il flusso di credenziali client. Ti consigliamo di fornire il client secret utilizzando Secret Manager.
Token di accesso dell'agente di servizio	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 dell'agente di servizio	Puoi scegliere Token ID nella sezione Autenticazione dell'agente di servizio, che ti consente di utilizzare il token ID dell'agente di servizio per l'autenticazione. In questo modo puoi accedere alle risorse Cloud Run.
Autenticazione TLS reciproca	Consulta la documentazione sull'autenticazione TLS reciproca.

Nota: se sono abilitate più opzioni di autenticazione, le opzioni con priorità più alta 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: sconsigliamo di utilizzare intervalli IP per autenticare le richieste di webhook. Se scegli di utilizzare l'IP di origine della richiesta per abilitare la connettività nel perimetro della tua rete, consenti le richieste provenienti dagli intervalli elencati all'indirizzo https://www.gstatic.com/ipranges/goog.json e nega le connessioni provenienti 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 workload di terze parti). Dialogflow non può garantire gli intervalli IP per le macchine che inviano richieste di webhook.

Nota: dopo il 15 agosto 2025, gli agenti esportati non conterranno più credenziali con 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 quando richiedi 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 i quali è possibile utilizzare il token OAuth.

Le richieste inviate all'URL dell'endpoint OAuth per ricevere un token non includono le intestazioni della richiesta 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 dell'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 singoli server che non condividono le cache dei token OAuth. Quando esegui il deployment di 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 potrebbe inviare al provider OAuth di terze parti.

Token ID dell'agente di servizio

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 sono necessarie autorizzazioni Identity and Access Management (IAM) aggiuntive per chiamarle.

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

Ad esempio, se l'URL webhook è:

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

il seguente URL deve essere incluso nei segmenti di pubblico personalizzati:

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

Inoltre, qualsiasi webhook può convalidare facoltativamente il token utilizzando le librerie client di Google o librerie open source come la libreria Google Auth per Node.js.

Se il tuo webhook è ospitato su Cloud Run e l'accesso avviene tramite un bilanciatore del carico, aggiungi l'URL del bilanciatore del carico come pubblico personalizzato a Cloud Run. Per saperne di più sui segmenti di pubblico personalizzati, consulta Imposta 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 li supporti.

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

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

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

• roles/iam.serviceAccountUser

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

• roles/iam.serviceAccountTokenCreator

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

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

Autenticazione di Secret Manager

Se utilizzi intestazioni di autenticazione, l'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 tuo secret se non ne hai uno.
2. Concedi all'agente di servizio Dialogflow il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) sul nuovo secret.
3. Copia la credenziale negli appunti.
4. Aggiungi una nuova versione del secret al tuo secret e incolla la credenziale 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 della versione del secret. Inserisci "Authorization" nel campo Chiave e incolla il nome della versione del secret nel campo Versione secret.
   • Per l'autenticazione di base con nome utente e password, fai clic su Versione secret in Autenticazione di base e incolla il nome della versione secret nel campo Versione 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 globali di Secret Manager. 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 impostazioni di autenticazione e URL specifiche per l'ambiente per ogni risorsa webhook.

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

Crea o modifica le risorse webhook

Dopo aver eseguito un servizio webhook, crea una risorsa webhook nell'agente che includa le 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 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 delle risorse webhook standard o le impostazioni delle risorse webhook flessibili.
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 dell'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 del 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, consulta 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 Environment	Risorsa Environment
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: Forbidden
• 404: non trovato
• 500: errore del server
• 503: servizio non disponibile

Dialogflow CX richiama un evento integrato di errore o timeout del webhook 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 API di rilevamento intent, il campo queryResult.webhookStatuses nella risposta di rilevamento intent contiene le informazioni sullo stato del webhook.

Nuovi tentativi automatici

Dialogflow CX riprova automaticamente le richieste in caso di determinati errori del webhook per migliorare la solidità. I nuovi tentativi automatici sono abilitati per impostazione predefinita e non possono essere disabilitati.

Dialogflow CX esegue un singolo nuovo tentativo per gli errori temporanei, come i timeout delle richieste, le connessioni di rete interrotte e i codici di stato HTTP nell'intervallo 5xx (come 500 Server fault o 503 Service unavailable). Gli errori del client terminale, come il codice di stato HTTP 404 Not found, non vanno a buon fine immediatamente senza un nuovo tentativo.

Latenza cumulativa e budget di timeout

Poiché Dialogflow CX riprova una volta in caso di 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 tentativo iniziale e dopo altri 5 secondi al tentativo di nuovo tentativo. Ciò comporta una latenza totale di circa 10 secondi prima che Dialogflow CX richiami i gestori degli 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 rigidi (ad esempio sistemi di telefonia o di risposta vocale interattiva (IVR) che terminano le chiamate dopo una finestra di timeout di 10 secondi), tieni conto di entrambi i tentativi impostando il timeout del webhook sulla metà della finestra consentita (ad esempio, tra 2,5 e 4 secondi).

Best practice per i nuovi tentativi

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

• Implementa l'idempotenza o la deduplicazione delle richieste nella logica del servizio webhook per elaborare in sicurezza le richieste duplicate.
• Se l'operazione del 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 risorse Cloud Run sicure per i webhook di Dialogflow CX. Ti consigliamo di proteggere le tue risorse. Se scegli di autenticarti con nome utente e password basati su URL o intestazioni HTTP, devi consentire l'accesso non autenticato alla tua risorsa Cloud Run.

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

Devi configurare manualmente questa integrazione nelle seguenti due situazioni:

1. Il service account Dialogflow CX Service Agent con il seguente indirizzo deve esistere per il progetto dell'agente:

   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 l'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 da quello dell'agente, devi fornire il ruolo IAM Cloud Run Invoker o Cloud Functions Invoker al account di servizio Dialogflow CX Service Agent nel progetto della risorsa Cloud Run.

Poi, seleziona Autenticazione agente di servizio > Token ID nella sezione Configurazione autenticazione.

Utilizzo di webhook containerizzati e del framework Go ezcx

Per implementare un webhook containerizzato utilizzando Go, consulta il framework ezcx di Go. 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 dei webhook all'interno della tua rete VPC. In questo modo, il traffico rimane all'interno della rete Google Cloud e vengono applicati IAMe 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 di 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 per essere applicata.

2. Il service account Dialogflow CX Service Agent con il seguente indirizzo deve esistere per il progetto dell'agente:

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

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

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   Inoltre, se Service Directory si trova in un progetto diverso da quello dell'agente Dialogflow CX, devi anche concedere il ruolo servicedirectory.viewer all'account dell'agente di servizio Dialogflow CX nel progetto che ospita l'agente Dialogflow CX.

3. Quando crei il webhook, specifica il servizio Service Directory, l'URL ed eventuali informazioni di autenticazione facoltative.

   Console

   

   API

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

   Seleziona un protocollo e una versione per il riferimento del 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 ai webhook.