Webhook

Webhook adalah layanan yang menghosting logika bisnis Anda atau memanggil layanan lain. Selama sesi, webhook memungkinkan Anda menggunakan data yang diekstrak oleh natural language processing Dialogflow untuk menghasilkan respons dinamis, memvalidasi data yang dikumpulkan, atau memicu tindakan di backend.

Webhook dapat berupa Webhook standar atau Webhook fleksibel. Dengan webhook standar, kolom permintaan dan respons ditentukan oleh Dialogflow. Dengan webhook fleksibel, Anda menentukan kolom permintaan dan respons.

Webhook standar

Dengan webhook standar, Anda menggunakan pesan respons dan permintaan yang ditentukan Dialogflow. Pesan permintaan memberikan banyak detail tentang sesi. Misalnya, halaman aktif saat ini, intent terbaru yang cocok, parameter value sesi, dan respons yang ditentukan agen akan disertakan.

Permintaan webhook standar

Saat fulfillment dengan webhook dipanggil, Dialogflow akan mengirimkan permintaan webhook POST HTTPS ke layanan webhook. Isi permintaan ini adalah objek JSON WebhookRequest dengan informasi tentang sesi tersebut.

Beberapa integrasi mengisi kolom WebhookRequest.payload dengan informasi tambahan. Misalnya, integrasi gateway ponsel Dialogflow CX menyediakan ID pemanggil pengguna akhir.

Lihat dokumentasi referensi WebhookRequest(V3) atau WebhookRequest(V3Beta1) untuk mengetahui detailnya.

Respons webhook standar

Setelah layanan webhook Anda menerima permintaan webhook, layanan tersebut perlu mengirimkan respons webhook. Batasan berikut berlaku pada respons Anda:

  • Respons harus terjadi dalam waktu tunggu yang Anda konfigurasi saat membuat resource webhook. Jika tidak, waktu tunggu permintaan akan habis.
  • Ukuran respons harus kurang dari atau sama dengan 64 KiB.

Lihat dokumentasi referensi WebhookResponse(V3) atau WebhookResponse(V3Beta1) untuk mengetahui detailnya.

Setelan resource webhook standar

Berikut adalah penjelasan setelan resource webhook untuk webhook standar:

Masa Berlaku Definisi
Nama tampilan Nama yang ditampilkan di konsol untuk webhook.
Waktu tunggu webhook habis Saat Dialogflow mengirimkan permintaan webhook ke layanan webhook Anda, waktu tunggu mungkin habis saat menunggu respons. Setelan ini mengontrol waktu tunggu dalam detik. Jika waktu tunggu habis, Dialogflow akan memanggil peristiwa webhook.error.timeout.
Jenis Tetapkan ke Service directory jika Anda menggunakan direktori layanan untuk akses jaringan pribadi. Jika tidak, tetapkan ke Generic web service.
URL webhook Masukkan alamat URL untuk layanan webhook Anda.
Subjenis Tetapkan ke Standar
Webhook khusus lingkungan Anda dapat menyediakan webhook khusus lingkungan.
Authentication Lihat bagian autentikasi.
Sertifikat CA kustom Kunci ini digunakan untuk mengupload sertifikat CA kustom.

Webhook fleksibel

Dengan webhook fleksibel, Anda dapat menentukan metode HTTP permintaan, parameter URL permintaan, serta kolom pesan permintaan dan respons. Permintaan hanya dapat menyediakan parameter value yang dipilih, dan respons hanya dapat memberikan parameter value pengganti. Batasan ini sebenarnya bermanfaat karena menyederhanakan antarmuka antara agen dan webhook. Kebutuhan untuk mengomunikasikan apa pun selain parameter value sesi antara agen dan webhook jarang terjadi. Metode ini juga menyederhanakan implementasi webhook Anda, karena pesan permintaan dan respons hanya berisi hal yang Anda butuhkan, dan Anda dapat menyediakan pesan webhook yang unik untuk berbagai skenario.

Permintaan webhook fleksibel

Saat membuat resource webhook untuk agen, Anda dapat menentukan hal berikut untuk permintaan webhook:

  • Metode HTTP yang digunakan untuk permintaan webhook yang dikirim ke layanan webhook Anda.
  • Nilai parameter sesi yang harus dikirim Dialogflow ke layanan webhook Anda menggunakan URL.
  • Jika memilih POST, PUT, atau PATCH sebagai metode, Anda dapat menentukan parameter value sesi yang harus dikirim Dialogflow ke layanan webhook melalui isi JSON permintaan.

Untuk mengirim parameter value sesi menggunakan URL permintaan atau isi JSON, gunakan referensi parameter seperti biasa. Anda tidak perlu meng-escape URL dari referensi parameter, dan tidak menggabungkan referensi dalam tanda kutip. Saat runtime, Dialogflow akan meng-escape nilai parameter sesuai kebutuhan. Daftar atau nilai gabungan akan diberikan sebagai JSON.

Saat menggunakan referensi parameter dalam isi JSON, Anda harus menggabungkan referensi dengan tanda kutip, apa pun jenis parameternya. Jika parameter tersebut sebenarnya merupakan skalar numerik, daftar, atau nilai komposit, Dialogflow akan menghapus tanda kutip saat mengirim permintaan saat runtime untuk mempertahankan jenis data parameter. Jenis skalar string akan tetap dikutip. Jika nilai skalar, daftar, atau gabungan numerik direferensikan dalam nilai string (misalnya: "This is a number: $session.params.size"), parameter ini akan diperlakukan sebagai string ("This is a number: 3").

Misalnya, Anda dapat memberikan parameter value sesi fruit dan size ke URL permintaan seperti ini:

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

Dan, untuk isi JSON permintaan seperti ini:

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

Respons webhook fleksibel

Saat membuat resource webhook untuk agen, Anda dapat menentukan parameter sesi yang harus ditetapkan Dialogflow ke kolom tertentu dari respons webhook saat runtime.

Batasan berikut berlaku pada respons Anda:

  • Respons harus terjadi dalam waktu tunggu yang Anda konfigurasi saat membuat resource webhook. Jika tidak, waktu tunggu permintaan akan habis.
  • Ukuran respons harus kurang dari atau sama dengan 64 KiB.

Gunakan format berikut untuk menentukan kolom skalar, daftar, atau komposit:

$.fully.qualified.path.to.field

Misalnya, pertimbangkan respons JSON berikut:

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

Untuk menentukan kolom "value", gunakan hal berikut:

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

Setelan resource webhook fleksibel

Berikut ini menjelaskan setelan resource webhook untuk webhook fleksibel:

Masa Berlaku Definisi
Nama tampilan Nama yang ditampilkan di konsol untuk webhook.
Waktu tunggu webhook habis Saat Dialogflow mengirimkan permintaan webhook ke layanan webhook Anda, waktu tunggu mungkin habis saat menunggu respons. Setelan ini mengontrol waktu tunggu dalam detik. Jika waktu tunggu habis, Dialogflow akan memanggil peristiwa webhook.error.timeout.
Jenis Tetapkan ke Service directory jika Anda menggunakan direktori layanan untuk akses jaringan pribadi. Jika tidak, tetapkan ke Generic web service.
URL webhook Berikan alamat URL untuk layanan webhook Anda, yang mungkin menyertakan referensi ke parameter sesi.
Subjenis Setel ke Fleksibel
Metode Tetapkan metode HTTP untuk permintaan webhook.
Isi permintaan Berikan isi JSON permintaan seperti yang dijelaskan di atas.
Konfigurasi respons Berikan parameter sesi yang harus ditetapkan ke kolom respons seperti yang dijelaskan di atas.
Webhook khusus lingkungan Anda dapat menyediakan webhook khusus lingkungan.
Authentication Lihat bagian autentikasi.
Sertifikat CA kustom Kunci ini digunakan untuk mengupload sertifikat CA kustom.

Persyaratan layanan webhook

Persyaratan berikut harus dipenuhi oleh layanan webhook Anda:

Authentication

Mengamankan layanan webhook Anda adalah hal yang penting, sehingga hanya Anda atau agen Dialogflow Anda yang diizinkan untuk membuat permintaan. Hal ini dikonfigurasi saat membuat resource webhook. Dialogflow CX mendukung mekanisme autentikasi berikut:

Masa Berlaku Definisi
Header autentikasi Untuk setelan webhook, Anda dapat menentukan key-value pair header HTTP opsional. Jika disediakan, Dialogflow akan menambahkan header HTTP ini ke permintaan webhook. Anda dapat memberikan satu pasangan dengan kunci authorization. Nilai header mendukung referensi parameter sesi dan penguraian fungsi sistem seperti dalam pesan respons statis.
Autentikasi dasar dengan nama pengguna dan sandi Untuk setelan webhook, Anda dapat menentukan nilai sandi dan nama pengguna login opsional. Jika disediakan, Dialogflow akan menambahkan header HTTP otorisasi ke permintaan webhook. Header ini memiliki bentuk: "authorization: Basic <base 64 encoding of the string username:password>".
OAuth pihak ketiga Anda dapat menentukan konfigurasi OAuth pihak ketiga sehingga Dialogflow akan mempertukarkan token akses dari penyedia OAuth dan menambahkannya di header HTTP otorisasi. Hanya alur kredensial klien yang didukung.
Token akses agen layanan Anda dapat memilih token akses di Autentikasi agen layanan agar dapat menggunakan token akses agen layanan untuk autentikasi. Akses ini dapat digunakan untuk mengakses Google Cloud API lainnya.
Token ID agen layanan Anda dapat memilih token ID di Autentikasi agen layanan agar dapat menggunakan token ID agen layanan untuk autentikasi. Akses ini dapat digunakan untuk mengakses layanan Cloud Function dan Cloud Run. Jika tidak ada opsi autentikasi lain yang digunakan, opsi ini diaktifkan secara default.
Autentikasi TLS bersama Lihat dokumentasi Autentikasi TLS bersama.

Verifikasi sertifikat HTTPS

Dialogflow secara default menggunakan penyimpanan kepercayaan default Google untuk memverifikasi sertifikat HTTPS. Jika Anda ingin menggunakan sertifikat yang tidak dikenali oleh penyimpanan trust default Google untuk server HTTPS, seperti sertifikat yang ditandatangani sendiri atau root certificate kustom, lihat Sertifikat CA kustom.

Webhook khusus lingkungan

Jika menggunakan lingkungan untuk mengisolasi sistem produksi dari sistem pengembangan (direkomendasikan), Anda dapat mengonfigurasi webhook agar spesifik per lingkungan. Untuk setiap resource webhook yang ditentukan, Anda dapat memberikan setelan autentikasi dan URL unik untuk setiap lingkungan yang telah Anda tentukan untuk agen.

Dengan demikian, Anda dapat mengembangkan dan menguji pembaruan kode webhook dengan aman sebelum men-deploy-nya ke produksi.

Membuat atau mengedit resource webhook

Setelah layanan webhook berjalan, Anda harus membuat resource webhook di agen Anda yang memiliki informasi konektivitas dan autentikasi. Setelah pembuatan, Anda juga dapat mengedit setelan resource webhook kapan saja.

Untuk membuat atau mengedit resource webhook:

Konsol

  1. Buka Konsol Dialogflow CX.
  2. Pilih project Google Cloud Anda.
  3. Pilih agen Anda.
  4. Pilih tab Kelola.
  5. Klik Webhook.
  6. Klik Buat atau klik resource webhook di daftar untuk mengedit.
  7. Masukkan setelan resource webhook standar atau setelan resource webhook fleksibel.
  8. Klik Save.

API

Untuk membuat resource webhook, lihat metode create untuk jenis Webhook. Untuk mengedit resource webhook (kecuali untuk setelan spesifik per lingkungan), lihat metode patch atau update untuk jenis Webhook.

Pilih protokol dan versi untuk referensi Webhook:

Protokol V3 V3beta1
REST Resource webhook Resource webhook
RPC Antarmuka webhook Antarmuka webhook
C++ WebhooksClient Tidak tersedia
C# WebhooksClient Tidak tersedia
Go WebhooksClient Tidak tersedia
Java WebhooksClient WebhooksClient
Node.js WebhooksClient WebhooksClient
PHP Tidak tersedia Tidak tersedia
Python WebhooksClient WebhooksClient
Ruby Tidak tersedia Tidak tersedia

Untuk mengedit setelan spesifik per lingkungan untuk webhook, lihat metode patch atau update untuk jenis Environment.

Pilih protokol dan versi untuk referensi Lingkungan:

Protokol V3 V3beta1
REST Referensi lingkungan Referensi lingkungan
RPC Antarmuka lingkungan Antarmuka lingkungan
C++ EnvironmentsClient Tidak tersedia
C# EnvironmentsClient Tidak tersedia
Go EnvironmentsClient Tidak tersedia
Java EnvironmentsClient EnvironmentsClient
Node.js EnvironmentsClient EnvironmentsClient
PHP Tidak tersedia Tidak tersedia
Python EnvironmentsClient EnvironmentsClient
Ruby Tidak tersedia Tidak tersedia

Error webhook

Jika layanan webhook Anda mengalami error saat menangani permintaan webhook, kode webhook harus menampilkan salah satu kode status HTTP berikut:

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Terlarang
  • 404 Tidak ditemukan
  • 500 Kesalahan server
  • 503 Service Unavailable

Dalam salah satu situasi error berikut, Dialogflow akan memanggil error webhook atau peristiwa bawaan waktu tunggu habis dan terus memproses seperti biasa:

  • Waktu tunggu respons terlampaui.
  • Kode status error diterima.
  • Respons tidak valid.
  • Layanan webhook tidak tersedia.

Selain itu, jika panggilan layanan webhook dipicu oleh panggilan API intent deteksi, kolom queryResult.webhookStatuses dalam respons intent deteksi berisi informasi status webhook.

Menggunakan Cloud Functions

Dialogflow terintegrasi dengan Cloud Functions, sehingga Anda dapat dengan mudah membuat webhook yang aman dan serverless. Jika Anda membuat fungsi yang berada di project yang sama dengan agen, agen Anda dapat memanggil webhook dengan aman tanpa memerlukan konfigurasi khusus.

Namun, ada dua situasi yang mengharuskan Anda menyiapkan integrasi ini secara manual:

  1. Akun layanan Dialogflow Service Agent dengan alamat berikut harus ada untuk project agen Anda: 
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Akun layanan khusus ini dan kunci terkait biasanya dibuat secara otomatis saat Anda membuat agen pertama untuk sebuah project. Jika agen dibuat sebelum 1 November 2020, Anda dapat memicu pembuatan akun layanan khusus ini:
    1. Buat agen baru untuk project.
    2. Jalankan perintah berikut: 
      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
  2. Jika fungsi webhook Anda berada di project yang berbeda dengan agen, Anda harus memberikan peran IAM Cloud Functions Invoker ke akun layanan Dialogflow Service Agent di project fungsi Anda.

Menggunakan webhook dalam container dan framework ezcx Go

Jika Anda ingin mengimplementasikan webhook dalam container menggunakan Go, lihat framework Go ezcx. Framework ini dapat menyederhanakan banyak langkah yang diperlukan saat membuat webhook.

Menggunakan Direktori Layanan untuk akses jaringan pribadi

Dialogflow terintegrasi dengan akses jaringan pribadi Direktori Layanan, sehingga dapat terhubung ke target webhook di dalam jaringan VPC Anda. Tindakan ini menjaga traffic dalam jaringan Google Cloud dan menerapkan IAM dan Kontrol Layanan VPC.

Untuk menyiapkan webhook yang menargetkan jaringan pribadi:

  1. Ikuti Konfigurasi jaringan pribadi Direktori Layanan untuk mengonfigurasi endpoint Direktori Layanan dan jaringan VPC Anda.

  2. Akun layanan Dialogflow Service Agent dengan alamat berikut harus ada untuk project agen Anda: 

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Berikan peran IAM berikut kepada akun layanan Dialogflow Service Agent:

    • servicedirectory.viewer project Direktori Layanan
    • servicedirectory.pscAuthorizedService project jaringan

  3. Berikan Layanan Direktori Layanan beserta URL dan informasi autentikasi opsional saat membuat webhook.

    Konsol

    Screenshot Webhook Direktori Layanan.

    API

    Lihat kolom serviceDirectory untuk jenis Webhook.

    Pilih protokol dan versi untuk referensi Webhook:

    Protokol V3 V3beta1
    REST Resource webhook Resource webhook
    RPC Antarmuka webhook Antarmuka webhook
    C++ WebhooksClient Tidak tersedia
    C# WebhooksClient Tidak tersedia
    Go WebhooksClient Tidak tersedia
    Java WebhooksClient WebhooksClient
    Node.js WebhooksClient WebhooksClient
    PHP Tidak tersedia Tidak tersedia
    Python WebhooksClient WebhooksClient
    Ruby Tidak tersedia Tidak tersedia

Untuk memecahkan masalah, Anda dapat menyiapkan cek uptime pribadi untuk memeriksa apakah Direktori Layanan Anda dikonfigurasi dengan benar.

Autentikasi agen layanan

Dialogflow dapat menghasilkan token ID atau token akses menggunakan agen layanan Dialogflow.

Token ditambahkan di header HTTP otorisasi saat Dialogflow memanggil webhook.

Token ID

Token ID dapat digunakan untuk mengakses layanan Cloud Function dan Cloud Run setelah Anda memberikan peran Invoker untuk 

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Jika layanan Cloud Function dan Cloud Run berada dalam project resource yang sama, Anda tidak memerlukan izin IAM tambahan untuk memanggilnya.

Audiens yang digunakan untuk membuat token ID adalah seluruh URL webhook, kecuali parameter kueri. Jika Anda menggunakan Cloud Run, pastikan URL ini didukung oleh audience Cloud Run. Misalnya, jika URL webhook adalah

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

URL berikut harus berada dalam audiens kustom.

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

Setiap webhook juga dapat memvalidasi token secara opsional menggunakan library klien Google atau library open source seperti github.com/googleapis/google-auth-library-nodejs.

Token akses

Token akses dapat digunakan untuk mengakses Google Cloud API lainnya setelah Anda memberikan peran yang diperlukan kepada 

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

Contoh dan pemecahan masalah

Lihat panduan cara kerja webhook.

Sebelumnya
Fulfillments
Berikutnya
Speech models