Webhook

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:

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:

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 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 tuoi 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:

• Deve gestire le richieste HTTPS. HTTP non è supportato. Se ospiti il servizio webhook sulla Google Cloud Platform utilizzando una soluzione di computing o computing serverless, consulta la documentazione del prodotto per la pubblicazione con HTTPS. Per altre opzioni di hosting, consulta Ottenere 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 non sia accessibile come webhook della directory dei servizi.
• Deve gestire le richieste e le risposte come descritto nella sezione relativa ai webhook standard o ai webhook flessibili.
• Se il tuo agente non si integra con l'accesso alla rete privata di Service Directory, le chiamate webhook sono considerate esterne al perimetro di servizio e vengono bloccate quando attivi i Controlli di servizio VPC. Gli endpoint con limitazioni 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 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:

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:

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

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 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.

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:

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 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 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, in modo da potersi connettere ai target 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 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 Service Directory insieme all'URL e alle informazioni di autenticazione facoltative durante la creazione dell'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 un controllo di uptime privato per verificare che Service Directory sia configurato correttamente.

Samples e risoluzione dei problemi

Consulta la guida illustrativa sui webhook.