Webhook

I webhook sono servizi che ospitano la logica aziendale o chiamano altri servizi. Durante una sessione, gli webhook ti consentono di utilizzare i dati estratti dall'elaborazione del linguaggio naturale degli agenti conversazionali (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 dagli agenti di conversazione (Dialogflow CX). Con un webhook flessibile, devi definire i campi di richiesta e risposta.

Webhook standard

Con i webhook standard, si utilizzano messaggi di richiesta e risposta definiti dagli agenti conversazionali (Dialogflow CX). Il messaggio di richiesta fornisce molti dettagli sulla sessione. Ad esempio, sono inclusi la pagina attiva corrente, l'intenzione associata di recente, i valori dei parametri di sessione e le risposte definite dall'agente.

Richiesta webhook standard

Quando fulfillment con un webhook, Gli agenti conversazionali (Dialogflow CX) inviano 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 con 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

Quando il servizio webhook riceve una richiesta, deve inviare una risposta webhook. Alla risposta si applicano le seguenti limitazioni:

• La risposta deve avvenire entro un timeout configurato quando crei la risorsa webhook, altrimenti la richiesta scadrà.
• La risposta deve essere 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 visualizzato nella console per il webhook.
Timeout webhook	Quando gli agenti conversazionali (Dialogflow CX) inviano una richiesta webhook al tuo servizio webhook, il timeout potrebbe verificarsi durante l'attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, gli agenti conversazionali (Dialogflow CX) richiamano 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 servizio webhook.
Sottotipo	Imposta su Standard
Webhook specifico per l'ambiente	Puoi fornire webhook specifici per l'ambiente.
Autenticazione	Consulta la sezione sull'autenticazione.
Certificato CA personalizzato	Questo viene utilizzato per caricare i certificati CA personalizzati.

Webhook flessibili

Con i webhook flessibili, devi definire 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 parametro selezionati, mentre la risposta può fornire solo valori di override dei parametri. Questa limitazione è effettivamente vantaggiosa, perché semplifica l'interfaccia tra l'agente e il webhook. Raramente è necessario comunicare qualcosa di diverso da i valori dei parametri di sessione tra un agente e un webhook. Semplifica inoltre l'implementazione del webhook, perché i messaggi di richiesta e risposta contengono solo ciò che e puoi fornire messaggi webhook univoci per vari scenari.

Richiesta di 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 webhook inviate al servizio webhook.
• Valori dei parametri di sessione che gli agenti conversazionali (Dialogflow CX) devono inviare al servizio webhook utilizzando l'URL.
• Se scegli POST, PUT o PATCH come metodo, puoi specificare i valori dei parametri di sessione che gli agenti conversazionali (Dialogflow CX) devono inviare al 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 riferimenti ai parametri come faresti normalmente. Non è necessario applicare la codifica URL al riferimento del parametro e non è necessario racchiuderlo tra virgolette. In fase di runtime, Gli agenti conversazionali (Dialogflow CX) eseguono l'URL con escape del valore parametro, se necessario. Un valore composto o un elenco verrà 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 è in realtà un valore scalare, un elenco o un valore composito numerico, agenti conversazionali (Dialogflow CX) rimuoverà le virgolette quando invia la richiesta in fase di esecuzione per preservare il tipo di dati del parametro. I tipi scalari di stringa rimarranno tra virgolette. Se si fa riferimento a un valore scalare, elenco o composto numerico all'interno di un valore di stringa (ad esempio: "Questo è un numero: $session.params.size"), il parametro viene considerato come una stringa ("Questo è un numero: 3").

Ad esempio, puoi fornire i valori dei parametri di sessione fruit e size all'URL di 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 gli agenti conversazionali (Dialogflow CX) devono impostare su campi specifici della risposta webhook in fase di esecuzione.

Alla risposta si applicano le seguenti limitazioni:

• La risposta deve avvenire entro un timeout configurato quando crei la risorsa webhook, altrimenti la richiesta scadrà.
• La risposta deve essere inferiore o uguale a 64 KiB.

Utilizza il seguente formato per specificare un campo scalare, un elenco o un campo 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", utilizza quanto segue:

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

Impostazioni flessibili delle risorse webhook

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

Termine	Definizione
Nome visualizzato	Il nome visualizzato nella console per il webhook.
Timeout webhook	Quando gli agenti conversazionali (Dialogflow CX) inviano una richiesta webhook al tuo servizio webhook, il timeout potrebbe verificarsi durante l'attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, gli agenti conversazionali (Dialogflow CX) richiamano un evento webhook.error.timeout.
Tipo	Imposta Service directory (Directory dei servizi) se utilizzi la directory dei servizi per l'accesso alla rete privata, altrimenti impostalo su Servizio web generico.
URL webhook	Fornisci l'indirizzo URL per il 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 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 sull'autenticazione.
Certificato CA personalizzato	Viene utilizzato per caricare certificati CA personalizzati.

Utilizza un modello personalizzato predefinito

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

1. Nella scheda Gestisci, fai clic su Webhook, quindi su + Crea.

2. In Sottotipo, seleziona Flessibile.

3. Fai clic su Configura utilizzando un 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 per l'API. Il modello compila automaticamente il modulo webhook in base al nome dell'API scelto.

   1. Se applicabile, puoi configurare manualmente i seguenti campi in base ai 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 l'webhook.

Requisiti del servizio webhook

Il servizio webhook deve soddisfare i seguenti requisiti:

• Deve gestire le richieste HTTPS. HTTP non è supportato. Se ospiti il servizio webhook sulla piattaforma Google Cloud utilizzando una soluzione di computing o cloud computing serverless, consulta la documentazione del prodotto per la pubblicazione con HTTPS. Per altre opzioni di hosting, consulta Ottieni un certificato SSL per il tuo dominio.
• L'URL per le richieste deve essere accessibile pubblicamente a meno che non sia ospitato come funzione Cloud Run o sia accessibile come webhook di Service Directory.
• Deve gestire le richieste e le risposte come descritto nei una sezione per un webhook standard o un webhook flessibile.
• Se l'agente non si integra con Accesso alla rete privata di Service Directory, le chiamate webhook sono considerate al di fuori del perimetro di servizio e sono bloccate quando abiliti i Controlli di servizio VPC. Service Directory supporta endpoint limitati. consulta le Service Directory per maggiori dettagli.

Autenticazione

Nota: gli IP di origine dei webhook fanno parte del sottoinsieme di quelli elencati all'indirizzo https://www.gstatic.com/ipranges/goog.json che esclude quelli elencati all'indirizzo https://www.gstatic.com/ipranges/cloud.json. Oltre a questo, Dialogflow non può fornire alcuna garanzia sulle intervalli IP per le macchine che inviano richieste webhook. Anziché limitare l'accesso tramite l'intervallo IP, è consigliabile utilizzare uno dei seguenti metodi di autenticazione elencati nella tabella seguente.

È importante proteggere il servizio webhook, in modo che solo tu o il tuo agente di agenti conversazionali (Dialogflow CX) siate autorizzati a effettuare richieste. Viene configurato durante la creazione di una risorsa webhook. Gli agenti conversazionali (Dialogflow CX) supportano i seguenti meccanismi di autenticazione:

Termine	Definizione
Intestazioni dell'autenticazione	Per le impostazioni del webhook, puoi specificare coppie chiave-valore facoltative dell'intestazione HTTP. Se fornite, gli agenti conversazionali (Dialogflow CX) aggiungono queste intestazioni HTTP alle richieste webhook. È comune fornire una singola coppia con una chiave authorization. I valori dell'intestazione supportano i riferimenti ai parametri di sessione e l'analisi del parsing delle funzioni di sistema, come nei messaggi di risposta statici.
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 specificato, gli agenti conversazionali (Dialogflow CX) aggiungono un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione è nel modulo: "authorization: Basic <base 64 encoding of the string username:password>".
OAuth di terze parti	Puoi specificare la configurazione OAuth di terze parti in modo che gli agenti conversazionali (Dialogflow CX) scambino un token di accesso dal provider OAuth e lo aggiungano all'intestazione HTTP di autorizzazione. È supportato solo il flusso delle credenziali client.
Token di accesso dell'agente di servizio	Puoi selezionare il token di accesso nell'autenticazione dell'agente di servizio per utilizzare i token di accesso dell'agente di servizio per l'autenticazione. Questo token può essere utilizzato per accedere ad altre API Google Cloud.
Token ID agente di servizio	Puoi selezionare il token ID nell'autenticazione dell'agente di servizio per utilizzare i token ID agente di servizio per l'autenticazione. Può essere utilizzato per accedere alle funzioni di Cloud Run e ai servizi Cloud Run.
Autenticazione TLS reciproca	Consulta la documentazione sull'autenticazione TLS reciproca.

Nota: se sono attivate più opzioni di autenticazione, quelle con priorità più alta hanno la precedenza. Ordine di priorità delle opzioni di autenticazione: Intestazioni di autenticazione, Autenticazione di base, OAuth di terze parti, Autorizzazione agente di servizio.

Verifica del certificato HTTPS

Per impostazione predefinita, gli agenti conversazionali (Dialogflow CX) utilizzano l'archivio attendibilità predefinito di Google per verificare i certificati HTTPS. Se intendi utilizzare certificati non riconosciuti da Google archivio di attendibilità predefinito per il server HTTPS, come i certificati autofirmati o certificati radice personalizzati, fai riferimento Certificati CA personalizzati.

Webhook specifici dell'ambiente

Se utilizzi gli ambienti per isolare i sistemi di produzione dai sistemi di sviluppo (opzione consigliata), puoi configurare gli webhook in modo che siano specifici per l'ambiente. Per ogni risorsa webhook che definisci, puoi fornire impostazioni di autenticazione e URL univoche per ogni ambiente che hai definito per l'agente.

Ciò ti consente di sviluppare e testare in modo sicuro gli aggiornamenti del codice dei webhook prima di eseguirne il deployment in produzione.

Crea o modifica risorse webhook

Una volta eseguito un servizio webhook, devi creare una risorsa webhook nell'agente con informazioni sulla connettività e sull'autenticazione. Dopo la creazione, puoi anche modificare le impostazioni della risorsa 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 fai clic su una risorsa webhook nell'elenco da modificare.
7. Inserisci le impostazioni delle risorse webhook standard o le impostazioni delle risorse webhook flessibili.
8. Fai clic su Salva.

API

Per creare una risorsa webhook, consulta il metodo create per il tipo Webhook. Per modificare una risorsa webhook (tranne le impostazioni specifiche dell'ambiente), consulta il metodo patch o update per il tipo Webhook. Vai al riferimento dell'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 modificare le impostazioni specifiche dell'ambiente per un webhook, vedi il metodo patch o update per il tipo Environment. Vai alla guida di riferimento dell'API Environment

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

Protocollo	V3	V3beta1
REST	Risorsa ambiente	Risorsa dell'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 mentre gestisce una richiesta webhook il codice webhook deve restituire uno dei seguenti codici di stato HTTP:

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

In una delle seguenti situazioni di errore, Gli agenti conversazionali (Dialogflow CX) richiamano un errore o un timeout del webhook evento integrato e continua l'elaborazione come di consueto:

• Timeout risposta superato.
• Codice di stato di errore ricevuto.
• La risposta non è valida.
• Il servizio webhook non è disponibile.

Inoltre, se la chiamata di servizio webhook è stato attivato da una chiamata API di rilevamento dell'intent, Il campo queryResult.webhookStatuses nella risposta di rilevamento dell'intent contiene le informazioni sullo stato del webhook.

Nuovi tentativi automatici

Gli agenti conversazionali (Dialogflow CX) includono meccanismi interni che riprovano automaticamente alcuni errori dei webhook per migliorare la robustezza. Solo gli errori non del terminale vengono nuovi tentativi (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 esegui la deduplica.

Utilizzo delle funzioni Cloud Run

Nota: questa sezione descrive come utilizzare le funzioni Cloud Run sicure per gli webhook degli agenti di conversazione (Dialogflow CX). Ti consigliamo di mantenere le funzioni al sicuro. Tuttavia, se scegli di autenticarti con nome utente e password basati su URL o intestazioni HTTP, devi consentire l'accesso non autenticato alla tua funzione.

Gli agenti di conversazione (Dialogflow CX) si integrano con le funzioni Cloud Run, in modo da poter creare facilmente un webhook sicuro e serverless. Se crei una funzione che si trova nello stesso progetto del tuo agente, basta selezionare Auth Service Agent -> ID Token nella configurazione di Auth, in modo che l'agente possa chiamare in modo sicuro il tuo webhook.

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

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

   [e-mail]

   Questo account di servizio speciale e la chiave associata di solito viene creato 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 dall'agente, devi fornire il ruolo IAM Invoker di Cloud Functions all'account di servizio Agente di servizio per gli agenti conversazionali (Dialogflow CX) nel progetto della funzione.
3. Seleziona Autorizzazione agente di servizio -> Token ID nella sezione di configurazione dell'autenticazione.

Utilizzo di webhook containerizzati e del framework ezcx di Go

Se vuoi implementare un webhook containerizzato utilizzando Go, consulta il framework Go ezcx. Questo framework può semplificare molti dei passaggi necessari per creare un webhook.

Utilizzo di funzioni Cloud Run con traffico solo interno

Nota: l'utilizzo delle funzioni Cloud Run al di fuori del perimetro di Controlli di servizio VPC del progetto dell'agente di agenti di conversazione (Dialogflow CX) per gli webhook non è supportato.

Le funzioni di Cloud Run sono configurate per accettare il traffico interno dalle reti VPC nello stesso o lo stesso perimetro SC VPC può essere usato come webhook, purché nello stesso progetto o nello stesso perimetro SC VPC.

Utilizzo di Service Directory per l'accesso alla rete privata

Gli agenti conversazionali (Dialogflow CX) si integrano con Accesso alla rete privata di Service Directory, in modo che possa connettersi 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 Configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint di Service Directory.

   Nota: gli agenti conversazionali (Dialogflow CX) memorizzano nella cache le informazioni di Service Directory per 90 secondi. Ciò significa che se aggiorni l'endpoint di Service Directory, saranno necessari 90 secondi prima che la modifica venga applicata. Inoltre, se configuri più endpoint per la ridondanza, agenti di conversazione (Dialogflow CX) potrebbe inviare traffico tramite un endpoint in stato di errore per 90 secondi.

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

   [e-mail]

   Concedi all'account di servizio degli agente di servizio conversazionali (Dialogflow CX) i seguenti ruoli IAM:
   • servicedirectory.viewer del progetto Service Directory
   • servicedirectory.pscAuthorizedService del progetto di rete

3. Fornisci il servizio Service Directory insieme all'URL e informazioni di autenticazione facoltative durante la creazione del webhook.

   Console

   

   API

   Consulta il campo serviceDirectory per il tipo Webhook. Vai al riferimento dell'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 controllo di uptime privato per verificare che Service Directory sia configurato correttamente.

Autorizzazione agente di servizio

Gli agenti conversazionali (Dialogflow CX) possono generare un token ID o un token di accesso utilizzando l'agente di servizio degli agenti conversazionali (Dialogflow CX).

Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando gli agenti conversazionali (Dialogflow CX) chiamano un webhook.

Token ID

Un token ID può essere utilizzato per accedere alle funzioni e ai servizi Cloud Run di Cloud Run dopo aver concesso il ruolo Invoker a

[e-mail]

Se le funzioni e i servizi Cloud Run si trovano nello stesso progetto di risorse, non è necessaria un'autorizzazione IAM aggiuntiva per richiamarli.

Il segmento di pubblico utilizzato per generare il token ID sarà l'intero URL webhook, tranne eventuali parametri di ricerca. Se utilizzi Cloud Run, assicurati che questo URL sia supportato dai segmenti di pubblico Cloud Run. Ad esempio, se l'URL del webhook è

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

il seguente URL deve trovarsi in segmenti di pubblico personalizzati.

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

Qualsiasi webhook può anche convalidare facoltativamente il token utilizzando le librerie client di Google o librerie open source come github.com/googleapis/google-auth-library-nodejs.

Token di accesso

Un token di accesso può essere utilizzato per accedere ad altre API Google Cloud dopo aver concesso i ruoli richiesti a

[e-mail]

Esempi e risoluzione dei problemi

Consulta le guida illustrativa sul webhook.