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 uno standard o uno 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.

Webhook standard

Con gli 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 del gateway di telefonia Dialogflow CX fornisce l'ID chiamante dell'utente finale.

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

Risposta webhook standard

Una volta che il servizio webhook riceve una richiesta webhook, deve inviare una risposta webhook. Alla tua risposta si applicano le seguenti limitazioni:

• La risposta deve avvenire entro un timeout che configuri quando crei la risorsa webhook, altrimenti la richiesta andrà in timeout.
• La risposta deve avere una dimensione inferiore o uguale a 64 KiB.

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

Impostazioni delle risorse webhook standard

Di seguito vengono descritte le impostazioni delle risorse webhook per i webhook standard:

Termine	Definizione
Nome visualizzato	Il nome mostrato nella console per il webhook.
Timeout del webhook	Quando Dialogflow CX invia una richiesta webhook al tuo servizio webhook, potrebbe verificarsi un timeout durante l'attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Dialogflow CX richiama un evento webhook.error.timeout.
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	Impostato 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 URL della richiesta e i campi dei messaggi di richiesta e risposta. La richiesta può fornire solo valori di parametri selezionati e la risposta può fornire solo valori di override dei parametri. Questa limitazione è in realtà vantaggiosa, perché semplifica l'interfaccia tra l'agente e il webhook. Raramente è necessario comunicare altro oltre ai valori dei parametri di sessione tra un agente e un webhook. Semplifica anche l'implementazione del webhook, perché i messaggi di richiesta e risposta contengono solo ciò di cui hai bisogno 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.
• Se scegli POST, PUT o PATCH come metodo, puoi specificare i valori dei parametri di sessione che Dialogflow CX deve inviare al tuo servizio webhook tramite il corpo JSON della richiesta.

Per inviare i valori dei parametri di sessione utilizzando l'URL della richiesta o il corpo JSON, utilizza i riferimenti ai parametri come faresti normalmente. Non è necessario eseguire l'escape dell'URL del riferimento al parametro e non è necessario racchiudere il riferimento tra virgolette. In fase di runtime, Dialogflow CX eseguirà l'escape dell'URL del valore parametro in base alle necessità. Un elenco o un valore composito verrà 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 numerico, un elenco o un valore composito, Dialogflow CX rimuoverà 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 viene fatto riferimento a un valore scalare, elenco o composito numerico all'interno di un valore stringa (ad esempio: "This is a number: $session.params.size"), il parametro verrà trattato come 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, in questo modo:

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

Risposta webhook flessibile

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

Alla tua risposta si applicano le seguenti limitazioni:

• La risposta deve avvenire entro un timeout che configuri quando crei la risorsa webhook, altrimenti la richiesta andrà in timeout.
• La risposta deve avere una dimensione inferiore o uguale a 64 KiB.

Utilizza il seguente formato per specificare un campo scalare, elenco o composto:

$.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" (valore), utilizza quanto segue:

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

Impostazioni flessibili delle risorse webhook

Di seguito sono descritte le impostazioni delle risorse webhook per i webhook flessibili:

Termine	Definizione
Nome visualizzato	Il nome mostrato nella console per il webhook.
Timeout del webhook	Quando Dialogflow CX invia una richiesta webhook al tuo servizio webhook, potrebbe verificarsi un timeout durante l'attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Dialogflow CX richiama un evento webhook.error.timeout.
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	Impostato 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 da impostare 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. Nella scheda Gestisci, fai clic su Webhook e poi su + Crea.

2. In Sottotipo, seleziona Flessibile.

3. Fai clic su Configura utilizzando il modello predefinito per attivare la funzionalità.

4. Nel menu a discesa Tipo di integrazione, seleziona Salesforce.

5. Nel menu a discesa Nome API, seleziona un nome API. Il modello compila automaticamente il modulo webhook in base al nome dell'API che scegli.

   1. Se applicabile, puoi configurare 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 per creare il webhook.

Requisiti del servizio webhook

Il tuo servizio webhook deve soddisfare i seguenti requisiti:

• Deve gestire le richieste HTTPS. HTTP non è supportato. Se ospiti il servizio webhook su Google Cloud Platform utilizzando una soluzione Compute o Serverless computing, consulta la documentazione del prodotto per la pubblicazione con HTTPS. Per altre opzioni di hosting, consulta Ottenere un certificato SSL per il tuo dominio.
• Il suo URL per le richieste deve essere accessibile pubblicamente, a meno che non sia ospitato come risorsa Cloud Run o non vi si acceda come webhook Service Directory.
• Deve gestire 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 vengono considerate al di fuori del perimetro di servizio e vengono bloccate quando vengono abilitati i Controlli di servizio VPC. Gli endpoint limitati sono supportati da Service Directory. Per maggiori dettagli, consulta Service Directory.

Autenticazione

È importante proteggere il servizio webhook, in modo che solo tu o il tuo agente Dialogflow CX siate autorizzati a effettuare richieste. Questa impostazione viene configurata durante la creazione o la modifica di una risorsa webhook. Dialogflow CX supporta i seguenti meccanismi di autenticazione:

Termine	Definizione
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. È 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	Ritirato
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 selezionare il token ID nell'autenticazione con service agent per utilizzare i token ID service agent per l'autenticazione. Può essere utilizzato per accedere alle risorse Cloud Run.
Autenticazione TLS reciproca	Consulta la documentazione relativa all'autenticazione TLS reciproca.

Nota: se sono attive più opzioni di autenticazione, hanno la precedenza quelle con priorità più elevata. Ordine di priorità delle opzioni di autenticazione: 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 abilitare la connettività al perimetro della tua rete, devi consentire le richieste provenienti dagli intervalli elencati all'indirizzo https://www.gstatic.com/ipranges/goog.json e poi negare qualsiasi connessione dagli intervalli elencati all'indirizzo https://www.gstatic.com/ipranges/cloud.json (che sono gli indirizzi di Google che possono essere utilizzati per il deployment di carichi di lavoro di terze parti). Oltre a questo, Dialogflow non può fornire alcuna garanzia sugli intervalli IP per le macchine che inviano richieste 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 e OAuth di terze parti.

OAuth di terze parti

Dialogflow CX può raccogliere un token di accesso da un provider OAuth di terze parti e aggiungerlo all'intestazione HTTP di autorizzazione quando effettua le richieste webhook.

Di seguito sono descritte le impostazioni delle risorse per OAuth di terze parti:

Termine	Definizione
ID client	L'ID client da utilizzare quando si richiede un token OAuth.
Client secret	Il segreto da utilizzare quando si richiede 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 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 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 una disponibilità elevata, 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 fornitore OAuth di terze parti.

Token ID service agent

Dialogflow CX può generare un token ID utilizzando l'agente di servizio Dialogflow CX.

Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando Dialogflow CX chiama un webhook.

Un token ID può essere utilizzato per accedere alle risorse Cloud Run dopo aver concesso le autorizzazioni del ruolo Invoker a

[e-mail]

Se le risorse Cloud Run si trovano nello stesso progetto di risorse, non hai bisogno di un'autorizzazione IAM aggiuntiva per chiamarle.

Il pubblico utilizzato per generare il token ID sarà l'intero URL webhook, esclusi i parametri di ricerca. Se utilizzi Cloud Run, assicurati che questo URL sia supportato dai gruppi di pubblico Cloud Run. Ad esempio, se l'URL del 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 github.com/googleapis/google-auth-library-nodejs.

Service account

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

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 faresti per qualsiasi altra entità. L'email del account di servizio verrà utilizzata per generare un token di accesso che verrà inviato nell'intestazione Authorization della richiesta webhook.

L'utente che configura il webhook per utilizzare i service account deve disporre delle seguenti autorizzazioni:

• roles/iam.serviceAccountUser

Affinché Dialogflow CX generi token, il service agent 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. Ecco i passaggi necessari per autenticare il webhook utilizzando i secret:

1. Crea il tuo segreto se non ne hai già uno.
2. Concedi al service agent 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. 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 appena aggiunto. Il formato del nome è projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
6. Apri la schermata di modifica del webhook, quindi:
   • Se utilizzi le intestazioni di autenticazione, crea una nuova intestazione della richiesta di versione del secret. Inserisci "Authorization" come Chiave e incolla il nome della versione del secret nella casella di input Versione del secret.
   • Se utilizzi 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 nella casella di input Versione del secret.
   • Se utilizzi OAuth di terze parti, fai clic su Versione del secret nella sezione OAuth di terze parti e incolla il nome della versione del secret nella casella di input Versione del secret.
7. Fai clic su Salva.

Nota: supportiamo solo Secret Manager globale. L'utilizzo dei secret regionali non è supportato.

Verifica del certificato HTTPS

Per impostazione predefinita, Dialogflow CX utilizza l'archivio 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 ambienti per isolare i sistemi di produzione dai sistemi di sviluppo (consigliato), puoi configurare i webhook in modo che siano specifici per l'ambiente. Per ogni risorsa webhook definita, puoi fornire impostazioni di autenticazione e URL unici per ogni ambiente definito per l'agente.

In questo modo puoi sviluppare e testare in sicurezza gli aggiornamenti del codice webhook prima di eseguirne il deployment in produzione.

Creare o modificare risorse webhook

Una volta in esecuzione un servizio webhook, devi creare una risorsa webhook nell'agente che contenga informazioni di connettività e autenticazione. Dopo la creazione, puoi anche modificare le impostazioni delle risorse webhook in qualsiasi momento.

Per creare o modificare una risorsa webhook:

Console

1. Apri la console Dialogflow CX.
2. Scegli il tuo progetto Google Cloud.
3. Seleziona il tuo agente.
4. Seleziona la scheda Gestisci.
5. Fai clic su Webhook.
6. Fai clic su Crea o su una risorsa webhook nell'elenco per modificarla.
7. Inserisci le impostazioni della risorsa webhook standard o le impostazioni della risorsa webhook flessibile.
8. Fai clic su Salva.

API

Per creare una risorsa webhook, consulta il metodo create per il tipo Webhook. Per modificare 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 webhook:

Protocollo	V3	V3beta1
REST	Risorsa webhook	Risorsa webhook
RPC	Interfaccia webhook	Interfaccia webhook
C++	WebhooksClient	Non disponibile
C#	WebhooksClient	Non disponibile
Go	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 modificare le 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 ambiente	Interfaccia ambiente
C++	EnvironmentsClient	Non disponibile
C#	EnvironmentsClient	Non disponibile
Go	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 tuo 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

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

• Timeout della risposta superato.
• Ricevuto codice di stato di errore.
• La risposta non è valida.
• Il servizio webhook non è disponibile.

Inoltre, 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 include meccanismi interni che riprovano automaticamente in caso di determinati errori webhook per migliorare la robustezza. Vengono ritentati solo gli errori non terminali (ad esempio, errori di timeout o di connessione).

Per ridurre la probabilità di chiamate duplicate:

• Imposta soglie di timeout del webhook più lunghe.
• Supporta l'idempotenza nella logica del webhook o deduplica.

Utilizzo di Cloud Run

Nota: questa sezione descrive come utilizzare le risorse Cloud Run sicure per i webhook Dialogflow CX. È consigliabile mantenere le risorse sicure. Tuttavia, 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 service agent -> Token ID nella configurazione di autenticazione in modo che l'agente possa chiamare in modo sicuro il webhook.

Tuttavia, ci sono due situazioni in cui devi configurare manualmente questa integrazione:

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

   [e-mail]

   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 tua 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 della risorsa Cloud Run.
3. Seleziona Service Agent Auth -> ID Token nella sezione Auth configuration (Configurazione autenticazione).

Utilizzo di webhook containerizzati e del framework Go ezcx

Se vuoi implementare un webhook containerizzato utilizzando Go, consulta il framework Go ezcx. Questo framework può semplificare molte delle fasi necessarie 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.

Le risorse Cloud Run configurate per accettare il traffico interno dalle reti VPC nello stesso progetto o nello stesso perimetro dei Controlli di servizio VPC possono essere utilizzate 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 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 se aggiorni l'endpoint di Service Directory, la modifica verrà applicata dopo 90 secondi. Inoltre, se stai configurando più endpoint per la ridondanza, Dialogflow CX potrebbe inviare traffico tramite un endpoint non funzionante per 90 secondi.

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

   [e-mail]

   Concedi i seguenti ruoli al account di servizio 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 dall'agente Dialogflow CX, devi anche concedere il ruolo servicedirectory.viewer all'account service agent Dialogflow CX nel progetto che ospita l'agente Dialogflow CX.

3. Fornisci il servizio Service Directory insieme all'URL e alle informazioni di autenticazione facoltative durante la creazione del 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
   Go	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

Consulta la guida illustrativa sui webhook.