Beberapa produk dan fitur sedang dalam proses penggantian nama. Fitur playbook dan alur generatif juga dimigrasikan ke satu konsol gabungan. Lihat detailnya.
Google uses AI technology to translate content into your preferred language. AI translations can contain errors.
Webhook
Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
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 CX
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 CX.
Dengan webhook fleksibel,
Anda menentukan kolom permintaan dan respons.
Kode status HTTP panggilan webhook juga tersedia di parameter permintaan $request.webhook_status_code.
Webhook standar
Dengan webhook standar,
Anda menggunakan pesan permintaan dan respons yang ditentukan Dialogflow CX.
Pesan permintaan memberikan banyak detail tentang sesi.
Misalnya, halaman aktif saat ini, maksud yang cocok baru-baru ini, nilai parameter sesi, dan respons yang ditentukan agen semuanya disertakan.
Permintaan webhook standar
Saat
pemenuhan
dengan webhook dipanggil,
Dialogflow CX mengirimkan permintaan webhook POST HTTPS ke layanan webhook Anda.
Isi permintaan ini adalah objek JSON WebhookRequest
dengan informasi tentang sesi.
Berikut ini deskripsi setelan resource webhook untuk webhook standar:
Istilah
Definisi
Nama tampilan
Nama yang ditampilkan di konsol untuk webhook.
Waktu tunggu webhook
Saat mengirim permintaan webhook ke layanan webhook Anda, Dialogflow CX mungkin mengalami waktu tunggu habis saat menunggu respons. Setelan ini mengontrol waktu tunggu tersebut dalam hitungan detik. Jika terjadi waktu tunggu habis, Dialogflow CX akan memanggil webhook.error.timeout event.
Dengan webhook fleksibel, Anda menentukan metode HTTP permintaan, parameter URL permintaan, dan kolom pesan permintaan dan respons. Permintaan hanya dapat memberikan nilai parameter yang dipilih, dan respons hanya dapat memberikan nilai penggantian parameter. Batasan ini sebenarnya bermanfaat, karena menyederhanakan antarmuka antara agen dan webhook. Jarang ada kebutuhan untuk mengomunikasikan apa pun selain nilai parameter sesi antara agen dan webhook. Hal ini juga menyederhanakan penerapan webhook Anda, karena pesan permintaan dan respons hanya berisi apa yang Anda butuhkan, dan Anda dapat memberikan pesan webhook 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 CX ke layanan webhook Anda menggunakan URL.
Jika Anda memilih POST, PUT, atau PATCH sebagai metode, Anda dapat menentukan nilai parameter sesi yang harus dikirim Dialogflow CX ke layanan webhook Anda melalui isi JSON permintaan.
Untuk mengirim nilai parameter sesi menggunakan URL permintaan atau isi JSON, gunakan
referensi parameter
seperti biasa.
Anda tidak perlu melakukan escape URL pada referensi parameter,
dan Anda tidak perlu menyertakan referensi dalam tanda petik.
Saat runtime,
Dialogflow CX akan meng-escape nilai parameter URL sesuai kebutuhan.
Daftar atau nilai gabungan akan diberikan sebagai JSON.
Saat menggunakan referensi parameter di isi JSON,
Anda harus menyertakan referensi dalam tanda petik,
terlepas dari jenis parameter.
Jika parameter sebenarnya adalah nilai skalar, daftar, atau komposit numerik, Dialogflow CX akan menghapus tanda petik saat mengirim permintaan saat runtime untuk mempertahankan jenis data parameter.
Jenis skalar string akan tetap dalam tanda kutip.
Jika nilai skalar, daftar, atau komposit numerik dirujuk dalam nilai string
(misalnya: "Ini adalah angka: $session.params.size"),
parameter akan diperlakukan sebagai string
("Ini adalah angka: 3").
Misalnya,
Anda dapat memberikan nilai parameter sesi fruit dan size
ke URL permintaan seperti ini:
Saat membuat resource webhook untuk agen, Anda dapat menentukan parameter sesi yang harus ditetapkan Dialogflow CX ke kolom tertentu dari respons webhook saat runtime.
Batasan berikut berlaku untuk respons Anda:
Respons harus terjadi dalam waktu tunggu yang Anda konfigurasi
saat membuat resource webhook,
jika tidak, permintaan akan mengalami waktu tunggu.
Ukuran respons harus kurang dari atau sama dengan 64 KiB.
Gunakan format berikut untuk menentukan kolom skalar, daftar, atau komposit:
Untuk menentukan kolom "value", gunakan yang berikut:
$.routes[0].legs[0].distance.value
Setelan resource webhook yang fleksibel
Berikut ini penjelasan setelan resource webhook untuk webhook fleksibel:
Istilah
Definisi
Nama tampilan
Nama yang ditampilkan di konsol untuk webhook.
Waktu tunggu webhook
Saat mengirim permintaan webhook ke layanan webhook Anda, Dialogflow CX mungkin mengalami waktu tunggu habis saat menunggu respons. Setelan ini mengontrol waktu tunggu tersebut dalam detik. Jika terjadi waktu tunggu habis, Dialogflow CX akan memanggil webhook.error.timeout event.
Dialogflow menawarkan template kustom yang telah ditentukan sebelumnya yang dapat Anda gunakan untuk mengintegrasikan webhook fleksibel dengan Salesforce CRM.
Di tab Manage, klik Webhooks, lalu + Create.
Di bagian Subtype, pilih Flexible.
Klik Konfigurasi menggunakan template standar untuk mengaktifkan fitur.
Di menu drop-down Integration type, pilih Salesforce.
Di menu drop-down Nama API, pilih nama API. Template akan otomatis mengisi formulir webhook berdasarkan nama API yang Anda pilih.
Anda dapat mengonfigurasi kolom berikut secara manual jika berlaku, berdasarkan
parameter Anda:
URL webhook
Metode
JSON isi permintaan
Konfigurasi Respons
Kolom OAuth yang wajib diisi akan ditandai di bagian Authentication.
Klik Simpan untuk membuat webhook.
Persyaratan layanan webhook
Persyaratan berikut harus dipenuhi oleh layanan webhook Anda:
Server harus menangani permintaan HTTPS. HTTP tidak didukung.
Jika Anda menghosting layanan webhook di Google Cloud Platform menggunakan solusi
Compute
atau
komputasi serverless, lihat dokumentasi produk untuk penayangan dengan HTTPS.
Untuk opsi hosting lainnya, lihat
Mendapatkan sertifikat SSL untuk domain Anda.
URL-nya untuk permintaan harus dapat diakses secara publik,
kecuali jika dihosting sebagai resource Cloud Run atau diakses sebagai webhook Service Directory.
Jika agen Anda tidak terintegrasi dengan
akses jaringan pribadi Service Directory,
panggilan webhook dianggap berada di luar perimeter layanan dan diblokir
saat mengaktifkan Kontrol Layanan VPC.
Endpoint terbatas didukung oleh Service Directory; lihat
Service Directory
untuk mengetahui detailnya.
Autentikasi
Penting untuk mengamankan layanan webhook Anda, sehingga hanya Anda atau agen Dialogflow CX Anda yang diizinkan untuk membuat permintaan.
Ini dikonfigurasi saat membuat atau mengedit resource webhook.
Dialogflow CX mendukung mekanisme berikut untuk autentikasi:
Istilah
Definisi
Header autentikasi
Untuk setelan webhook, Anda dapat menentukan pasangan nilai kunci header HTTP opsional. Jika disediakan, Dialogflow CX akan menambahkan header HTTP ini ke permintaan webhook. Umumnya, satu pasangan dengan kunci authorization akan diberikan. Nilai header mendukung referensi parameter sesi dan penguraian fungsi sistem seperti dalam pesan respons statis. Jika Anda menggunakan kredensial statis untuk header authorization, sebaiknya berikan kredensial Anda menggunakan Secret Manager.
Autentikasi dasar dengan nama pengguna dan sandi
Untuk setelan webhook, Anda dapat menentukan nilai nama pengguna dan sandi login opsional. Jika disediakan, Dialogflow CX akan menambahkan header HTTP otorisasi ke permintaan webhook. Header ini memiliki format: "authorization: Basic <base 64 encoding of the string username:password>". Sebaiknya Anda memberikan nama pengguna dan sandi menggunakan Secret Manager.
OAuth pihak ketiga
Anda dapat menentukan konfigurasi OAuth Pihak ketiga sehingga Dialogflow CX menukar token akses dari sistem OAuth dan menambahkannya di header HTTP otorisasi. Hanya alur kredensial klien yang didukung. Sebaiknya berikan secret klien Anda menggunakan Secret Manager.
Token akses agen layanan
Dihentikan
Akun layanan
Anda dapat menggunakan akun layanan untuk autentikasi. Hal ini dapat digunakan untuk mengakses Google Cloud API lainnya.
Token ID agen layanan
Anda dapat memilih token ID di Autentikasi agen layanan untuk menggunakan token ID agen layanan untuk autentikasi. Hal ini dapat digunakan untuk mengakses resource Cloud Run.
Dialogflow CX dapat mengumpulkan token akses dari penyedia OAuth pihak ketiga dan menambahkannya ke header HTTP otorisasi saat membuat permintaan webhook.
Berikut ini penjelasan setelan resource untuk OAuth pihak ketiga:
Istilah
Definisi
Client ID
Client ID yang akan digunakan saat meminta token OAuth.
Rahasia Klien
Secret yang akan digunakan saat meminta token OAuth. Sebaiknya berikan secret klien Anda menggunakan Secret Manager.
URL Endpoint OAuth
URL yang akan digunakan untuk meminta token OAuth.
Cakupan OAuth
Daftar cakupan yang dipisahkan koma yang dapat digunakan untuk token OAuth.
Permintaan yang dikirim ke URL Endpoint OAuth untuk menerima token tidak menyertakan header permintaan kustom yang dikonfigurasi untuk permintaan webhook. Anda dapat meneruskan informasi kustom ke server OAuth sebagai parameter dalam string kueri URL endpoint OAuth.
Jika resource 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
audiens Cloud Run.
Misalnya, jika URL webhook adalah
Perhatikan bahwa jika webhook Anda dihosting di Cloud Run dan diakses
melalui load balancer, tambahkan URL load balancer Anda sebagai audiens kustom ke
Cloud Run Anda. Untuk mengetahui informasi selengkapnya, lihat
Menetapkan audiens kustom untuk layanan.
Akun Layanan
Akun layanan dapat digunakan untuk mengautentikasi permintaan webhook ke Google API mana pun yang mendukungnya.
Karena akun layanan adalah akun utama, akun layanan dapat mengakses resource dalam project Anda dengan memberinya peran, seperti yang Anda lakukan untuk akun utama lainnya.
Email akun layanan akan digunakan untuk
membuat token akses
yang akan dikirim di header Authorization permintaan webhook.
Pengguna yang mengonfigurasi webhook untuk menggunakan akun layanan
harus memiliki izin berikut:
roles/iam.serviceAccountUser
Agar Dialogflow CX dapat membuat token, Agen Layanan Dialogflow harus memiliki izin berikut:
roles/iam.serviceAccountTokenCreator
Akun layanan juga harus memiliki izin untuk mengakses layanan yang menghosting webhook.
Autentikasi Secret Manager
Jika Anda menggunakan header autentikasi, autentikasi dasar dengan nama pengguna dan sandi, atau
OAuth pihak ketiga, Anda dapat menyimpan kredensial sebagai secret menggunakan
Secret Manager. Berikut adalah langkah-langkah yang diperlukan untuk mengautentikasi webhook Anda menggunakan rahasia:
Jika Anda menggunakan header autentikasi, masukkan Bearer <YOUR_CREDENTIAL>.
Jika Anda menggunakan autentikasi nama pengguna dan sandi dasar, masukkan
<YOUR_USERNAME>:<YOUR_PASSWORD>.
Jangan sertakan karakter baris baru di akhir.
Salin nama versi rahasia yang baru saja Anda tambahkan. Format namanya adalah
projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
Buka layar pengeditan webhook, lalu:
Jika Anda menggunakan header otentikasi, buat Header permintaan versi Secret baru.
Masukkan "Authorization" sebagai Kunci, dan tempel nama versi secret ke kotak input
Versi secret.
Jika Anda menggunakan autentikasi nama pengguna dan sandi dasar, klik Versi secret
di bagian Autentikasi Dasar dan tempel nama versi secret ke kotak input Versi secret.
Jika Anda menggunakan OAuth pihak ketiga, klik Versi rahasia di bagian OAuth pihak ketiga
dan tempel nama versi rahasia ke kotak input Versi rahasia.
Klik Simpan.
Verifikasi sertifikat HTTPS
Secara default, Dialogflow CX menggunakan penyimpanan tepercaya default Google untuk memverifikasi sertifikat HTTPS. Jika Anda ingin menggunakan sertifikat yang tidak dikenali oleh trust store default Google untuk server HTTPS Anda, seperti sertifikat yang ditandatangani sendiri atau root certificate kustom, lihat Sertifikat CA kustom.
Webhook khusus lingkungan
Jika Anda menggunakan
lingkungan
untuk mengisolasi sistem produksi dari sistem pengembangan (direkomendasikan),
Anda dapat mengonfigurasi webhook agar spesifik per lingkungan.
Untuk setiap resource webhook yang Anda tentukan,
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 perlu membuat resource webhook di agen yang memiliki informasi konektivitas dan autentikasi.
Setelah pembuatan, Anda juga dapat mengedit setelan resource webhook kapan saja.
Jika layanan webhook Anda mengalami error saat menangani permintaan webhook, kode webhook Anda 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 situasi error berikut,
Dialogflow CX memanggil error webhook atau waktu tunggu
peristiwa bawaan
dan melanjutkan pemrosesan 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 deteksi maksud,
kolom queryResult.webhookStatuses dalam respons deteksi maksud
berisi informasi status webhook.
Percobaan ulang otomatis
Dialogflow CX menyertakan mekanisme internal yang otomatis mencoba lagi error webhook tertentu untuk meningkatkan keandalan. Hanya error non-terminal yang dicoba lagi (misalnya, error waktu tunggu atau koneksi).
Untuk mengurangi kemungkinan panggilan duplikat:
Tetapkan nilai minimum waktu tunggu webhook yang lebih lama.
Mendukung idempotensi dalam logika webhook atau menghapus duplikat.
Menggunakan Cloud Run
Dialogflow CX terintegrasi dengan
Cloud Run,
sehingga Anda dapat membuat webhook serverless yang aman.
Jika Anda membuat resource Cloud Run yang berada di project yang sama dengan agen Anda, pilih Service Agent Auth -> ID Token di konfigurasi Auth agar agen Anda dapat memanggil webhook Anda dengan aman.
Namun, ada dua situasi
saat Anda harus menyiapkan integrasi ini secara manual:
Akun layanan khusus ini dan kunci terkait
biasanya dibuat secara otomatis
saat Anda membuat agen pertama untuk project.
Jika agen Anda dibuat sebelum 1 November 2020, Anda dapat memicu pembuatan akun layanan khusus ini:
Jika fungsi webhook Anda berada di project yang berbeda dengan agen, Anda harus memberikan peran IAMCloud Run Invoker atau Cloud Functions Invoker
ke akun layanan Agen Layanan Dialogflow CX
di project resource Cloud Run Anda.
Pilih Service Agent Auth -> ID Token di bagian konfigurasi Auth.
Menggunakan webhook dalam container dan framework Go ezcx
Jika Anda ingin menerapkan webhook yang di-container menggunakan Go, lihat
framework ezcx Go.
Framework ini dapat menyederhanakan banyak langkah yang diperlukan saat membuat webhook.
Menggunakan Cloud Run dengan traffic hanya internal
Resource Cloud Run yang disiapkan untuk menerima traffic internal
dari jaringan VPC dalam project yang sama atau perimeter Kontrol Layanan VPC
yang sama dapat digunakan sebagai webhook selama agen berada dalam project yang sama
atau perimeter Kontrol Layanan VPC yang sama.
Menggunakan Service Directory untuk akses jaringan pribadi
Berikan peran berikut ke akun layanan Agen Layanan Dialogflow CX di project tempat Service Directory Anda berada:
servicedirectory.viewer
servicedirectory.pscAuthorizedService
Selain itu, jika Service Directory Anda berada dalam project yang berbeda dengan agen Dialogflow CX, Anda juga perlu memberikan peran servicedirectory.viewer ke akun Agen Layanan Dialogflow CX dalam project yang menghosting agen Dialogflow CX Anda.
Berikan Layanan Direktori Layanan beserta URL
dan informasi autentikasi opsional saat membuat webhook.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2026-06-12 UTC."],[],[]]