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 da Conversational Agents (Dialogflow CX). Con un webhook flessibile, puoi definire i campi di richiesta e risposta.

Webhook standard

Con i webhook standard, utilizzi i messaggi di richiesta e risposta definiti da Conversational Agents (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 viene chiamato un servizio di evasione con un webhook, gli agenti conversazionali (Dialogflow CX) inviano una richiesta webhook POST HTTPS al 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

Una volta che il servizio webhook riceve una richiesta, deve inviare una risposta. 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 avere dimensioni inferiori o uguali a 64 KiB.

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

Impostazioni della risorsa webhook standard

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

Termine Definizione
Nome visualizzato Il nome visualizzato nella console per l'webhook.
Timeout webhook Quando Conversational Agents (Dialogflow CX) invia una richiesta webhook al tuo servizio webhook, potrebbe scadere il tempo di attesa mentre attende una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Conversational Agents (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 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 Viene utilizzato per caricare certificati CA personalizzati.

Webhook flessibili

Con gli webhook flessibili, puoi 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 è in realtà vantaggiosa, poiché semplifica l'interfaccia tra l'agente e l'webhook. Raramente è necessario comunicare qualcos'altro oltre ai valori dei parametri della sessione tra un agente e un webhook. Semplifica anche l'implementazione degli webhook, poiché i messaggi di richiesta e risposta contengono solo ciò che ti serve e puoi fornire messaggi webhook unici 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 i 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 esecuzione, Conversational Agents (Dialogflow CX) eseguirà la codifica URL del valore parametro in base alle esigenze. 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 a un valore scalare, di elenco o composito numerico viene fatto riferimento all'interno di un valore di stringa (ad esempio: "Questo è un numero: $session.params.size"), il parametro verrà trattato come 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 Conversational Agents (Dialogflow CX) deve 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 avere dimensioni inferiori o uguali 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 sono descritte le impostazioni delle risorse webhook per i webhook flessibili:

Termine Definizione
Nome visualizzato Il nome visualizzato nella console per l'webhook.
Timeout webhook Quando Conversational Agents (Dialogflow CX) invia una richiesta webhook al tuo servizio webhook, potrebbe scadere il tempo di attesa mentre attende una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Conversational Agents (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 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.

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 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
      • Corpo JSON 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:

Autenticazione

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

Termine Definizione
Intestazioni di autenticazione Per le impostazioni del webhook, puoi specificare coppie chiave-valore facoltative dell'intestazione HTTP. Se fornite, Conversational Agents (Dialogflow CX) aggiunge 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 di sistema delle funzioni, 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, Conversational Agents (Dialogflow CX) aggiunge un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione è del tipo: "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 di conversazione (Dialogflow CX) scambino un token di accesso dal sistema 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 e ai servizi Cloud Run.
Autenticazione TLS reciproca Consulta la documentazione sull'autenticazione TLS reciproca.

OAuth di terze parti

Gli agenti conversazionali (Dialogflow CX) possono raccogliere un token di accesso da un provider OAuth di terze parti e aggiungerlo all'intestazione HTTP di autorizzazione quando effettuano 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 per richiedere un token OAuth.
Client secret Il segreto da utilizzare per richiedere un token OAuth.
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 delle richieste personalizzate configurate per la richiesta webhook. Puoi passare informazioni personalizzate al server OAuth come parametri all'interno della stringa di query dell'URL dell'endpoint OAuth.

Token di accesso dell'agente di servizio

Conversational Agents (Dialogflow CX) può generare un token ID o un token di accesso utilizzando l'agente di servizio Conversational Agents (Dialogflow CX).

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

Token ID

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

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Se le funzioni e i servizi Cloud Run si trovano nello stesso progetto di risorse, non è necessaria un'autorizzazione IAM aggiuntiva per chiamarli.

Il segmento di pubblico utilizzato per generare il token ID sarà l'intero URL dell'webhook, ad eccezione dei parametri di query. 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 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 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

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

Verifica del certificato HTTPS

Per impostazione predefinita, Conversational Agents (Dialogflow CX) utilizza l'archivio attendibilità predefinito di Google per verificare i certificati HTTPS. Se intendi utilizzare certificati non riconosciuti dall'archivio attendibile 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 i sistemi di produzione da quelli 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.

In questo modo, puoi sviluppare e testare in sicurezza gli aggiornamenti del codice webhook prima di implementarli in produzione.

Creare o modificare le risorse webhook

Una volta eseguito un servizio webhook, devi creare una risorsa webhook nell'agente con informazioni su connettività e 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 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.

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

Per modificare le impostazioni specifiche dell'ambiente per un webhook, consulta il metodo patch o update per il tipo 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

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

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

  • È stato superato il timeout della risposta.
  • Codice di stato di errore ricevuto.
  • La risposta non è valida.
  • Il servizio webhook non è disponibile.

Inoltre, se la chiamata al servizio webhook è stata attivata da una chiamata all'API di rilevamento dell'intenzione, il campo queryResult.webhookStatuses nella risposta al rilevamento dell'intenzione contiene le informazioni sullo stato del webhook.

Nuovi tentativi automatici

Conversational Agents (Dialogflow CX) include meccanismi interni che tentano automaticamente di nuovo in caso di determinati errori webhook per migliorare la robustezza. Verranno eseguiti nuovi tentativi solo per gli errori non terminali (ad esempio timeout o errori di connessione).

Per ridurre la probabilità di chiamate duplicate:

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

Utilizzo di Cloud Run Functions

Conversational Agents (Dialogflow CX) si integra 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:
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    In genere, questo account di servizio speciale e la chiave associata vengono 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 Invoker di Cloud Functions all'account di servizio Agente di servizio per gli agenti conversazionali (Dialogflow CX) nel progetto della funzione.
  3. Seleziona Auth agente di servizio -> Token ID nella sezione di configurazione dell'autenticazione.

Utilizzo di webhook containerizzati e del framework ezcx per 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 Cloud Run functions con traffico solo interno

Le funzioni 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 purché 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

Gli agenti conversazionali (Dialogflow CX) si integrano con l'accesso alla rete privata di Service Directory, pertanto possono connettersi ai target webhook all'interno della 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 di Service Directory.

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

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Concedi all'account di servizio Agente di servizio per gli agenti conversazionali (Dialogflow CX) i seguenti ruoli IAM:

    • servicedirectory.viewer del progetto Service Directory
    • servicedirectory.pscAuthorizedService del progetto di rete
  3. Fornisci il servizio Directory dei servizi insieme all'URL e alle informazioni di autenticazione facoltative durante la creazione dell'webhook.

    Console

    Screenshot dell&#39;webhook di Service Directory.

    API

    Consulta il campo serviceDirectory per il tipo 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

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

Samples e risoluzione dei problemi

Consulta la guida illustrativa sui webhook.