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

Anda juga dapat mengakses kode status HTTP panggilan webhook menggunakan 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 akan mengirim permintaan webhook POST HTTPS ke layanan webhook Anda. Isi permintaan ini adalah objek JSON WebhookRequest dengan informasi tentang sesi.

Beberapa integrasi mengisi kolom WebhookRequest.payload dengan informasi tambahan. Misalnya, integrasi Gateway Telepon Dialogflow CX memberikan ID penelepon pengguna akhir.

Untuk mengetahui detailnya, lihat dokumentasi referensi WebhookRequest (V3) atau WebhookRequest (V3Beta1).

Respons webhook standar

Setelah layanan webhook Anda menerima permintaan, layanan tersebut harus mengirim respons yang memenuhi persyaratan berikut:

• Respons harus terjadi dalam waktu tunggu yang dikonfigurasi saat membuat resource webhook.
• Respons harus berukuran 64 KiB atau lebih kecil.

Untuk mengetahui detailnya, lihat dokumentasi referensi WebhookResponse (V3) atau WebhookResponse (V3Beta1).

Setelan resource webhook standar

Tabel berikut menjelaskan setelan resource webhook untuk webhook standar:

X	Item
Nama tampilan	Nama yang ditampilkan di konsol untuk webhook.
Waktu tunggu webhook	Saat Dialogflow CX mengirim permintaan HTTP ke layanan webhook Anda, setelan ini mengontrol waktu tunggu dalam detik untuk setiap upaya permintaan individual, bukan keseluruhan giliran percakapan. Jika upaya kehabisan waktu atau gagal dengan error sementara, Dialogflow CX akan otomatis mencoba lagi sekali. Percobaan ulang ini dapat menghasilkan total waktu penyelesaian hingga dua kali lipat nilai waktu tunggu yang dikonfigurasi sebelum menampilkan error. Jika terjadi waktu tunggu setelah mencoba lagi, Dialogflow CX akan memanggil peristiwa webhook.error.timeout. Untuk mengetahui detailnya, lihat Percobaan ulang otomatis.
Jenis	Setel ke Service directory jika Anda menggunakan service directory untuk akses jaringan pribadi, atau setel ke Generic web service.
URL webhook	Berikan alamat URL untuk layanan webhook Anda.
Subjenis	Tetapkan ke Standard.
Webhook khusus lingkungan	Anda dapat menyediakan webhook khusus lingkungan.
Autentikasi	Lihat bagian Autentikasi.
Sertifikat CA kustom	Digunakan untuk mengupload sertifikat CA kustom.

Webhook fleksibel

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. Hal ini menyederhanakan antarmuka antara agen dan webhook, karena jarang ada kebutuhan untuk mengomunikasikan hal lain selain nilai parameter sesi. 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.
• Nilai parameter sesi yang harus dikirim Dialogflow CX ke layanan webhook Anda melalui isi JSON permintaan jika Anda memilih POST, PUT, atau PATCH sebagai metode.

Untuk mengirim nilai parameter sesi menggunakan URL permintaan atau isi JSON, gunakan referensi parameter. Anda tidak perlu melakukan escape URL pada referensi parameter atau menyertakannya dalam tanda petik. Saat runtime, Dialogflow CX melakukan escape pada nilai parameter URL sesuai kebutuhan. Daftar atau nilai gabungan disediakan 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 skalar numerik, daftar, atau nilai komposit 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 sebagai berikut:

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

Dan, ke isi JSON permintaan sebagai berikut:

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

Respons webhook yang fleksibel

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

Respons Anda harus memenuhi batasan berikut:

• Respons harus terjadi dalam waktu tunggu yang dikonfigurasi saat membuat resource webhook, jika tidak, permintaan akan kehabisan waktu.
• Ukuran respons maksimal 64 KiB.

Untuk menentukan kolom skalar, daftar, atau komposit, gunakan format berikut:

$.fully.qualified.path.to.field

Misalnya, perhatikan respons JSON berikut:

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

Untuk menentukan kolom "value", gunakan yang berikut:

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

Setelan resource webhook yang fleksibel

Tabel berikut menjelaskan setelan resource webhook untuk webhook fleksibel.

X	Item
Nama tampilan	Nama yang ditampilkan di konsol untuk webhook.
Waktu tunggu webhook	Saat Dialogflow CX mengirim permintaan HTTP ke layanan webhook Anda, setelan ini mengontrol waktu tunggu dalam detik untuk setiap upaya permintaan individual, bukan keseluruhan giliran percakapan. Jika upaya kehabisan waktu atau gagal dengan error sementara, Dialogflow CX akan otomatis mencoba lagi sekali. Percobaan ulang ini dapat menghasilkan total waktu penyelesaian hingga dua kali lipat nilai waktu tunggu yang dikonfigurasi sebelum menampilkan error. Jika terjadi waktu tunggu setelah mencoba lagi, Dialogflow CX akan memanggil peristiwa webhook.error.timeout. Untuk mengetahui detailnya, lihat Percobaan ulang otomatis.
Jenis	Setel ke Service directory jika Anda menggunakan service directory untuk akses jaringan pribadi, atau setel ke Generic web service.
URL webhook	Berikan alamat URL untuk layanan webhook Anda, yang dapat mencakup 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 disetel ke kolom respons seperti yang dijelaskan di atas.
Webhook khusus lingkungan	Anda dapat menyediakan webhook khusus lingkungan
Autentikasi	Lihat bagian autentikasi.
Sertifikat CA kustom	Digunakan untuk mengupload sertifikat CA kustom.

Menggunakan template kustom standar

Dialogflow menawarkan template kustom yang telah ditentukan sebelumnya yang dapat Anda gunakan untuk mengintegrasikan webhook fleksibel dengan Salesforce CRM.

1. Buka tab Manage, pilih Webhooks, lalu klik Create.
2. Di bagian Subtype, pilih Flexible.
3. Klik Konfigurasi menggunakan template standar.
4. Di menu Integration type, pilih Salesforce.
5. Di menu API name, pilih nama API. Template akan otomatis mengisi formulir webhook berdasarkan nama API yang Anda pilih.
   1. Konfigurasi kolom berikut secara manual jika berlaku, berdasarkan parameter Anda:
      • URL webhook
      • Metode
      • JSON isi permintaan
      • Konfigurasi Respons
   2. Kolom OAuth yang wajib diisi akan ditandai di bagian Authentication.
6. Klik Simpan.

Persyaratan layanan webhook

Layanan webhook Anda harus memenuhi persyaratan berikut:

• Menangani permintaan HTTPS. HTTP tidak didukung. Jika Anda menghosting layanan webhook di Google Cloud menggunakan solusi Compute atau komputasi serverless, lihat dokumentasi untuk penayangan dengan HTTPS. Untuk opsi hosting lainnya, lihat Mendapatkan sertifikat SSL untuk domain Anda.
• Pastikan URL layanan webhook dapat diakses secara publik, kecuali jika dihosting sebagai resource Cloud Run atau diakses sebagai webhook Service Directory.
• Tangani permintaan dan respons seperti yang dijelaskan di bagian webhook standar atau webhook fleksibel.
• Jika agen Anda tidak terintegrasi dengan akses jaringan pribadi Service Directory, panggilan webhook berada di luar perimeter layanan dan diblokir saat mengaktifkan Kontrol Layanan VPC. Service Directory mendukung endpoint terbatas; untuk mengetahui detailnya, lihat Service Directory.

Autentikasi

Amankan layanan webhook Anda sehingga hanya Anda atau agen Dialogflow CX Anda yang dapat membuat permintaan. Konfigurasi ini saat membuat atau mengedit resource webhook. Dialogflow CX mendukung mekanisme autentikasi berikut:

X	Item
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 parsing 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 sandi dan nama pengguna 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. Token ini dapat digunakan untuk mengakses Google Cloud API lainnya.
Token ID agen layanan	Anda dapat memilih token ID di bagian Autentikasi agen layanan, yang memungkinkan Anda menggunakan Token ID agen layanan untuk autentikasi. Dengan demikian, Anda dapat mengakses resource Cloud Run.
Autentikasi TLS bersama	Lihat dokumentasi Autentikasi TLS bersama.

Catatan: Jika beberapa opsi autentikasi diaktifkan, opsi dengan prioritas lebih tinggi akan diutamakan. Urutan prioritasnya adalah sebagai berikut: Header autentikasi, Autentikasi dasar, OAuth pihak ketiga, Autentikasi agen layanan.

Catatan: Sebaiknya jangan gunakan rentang IP untuk mengautentikasi permintaan webhook. Jika Anda memilih untuk menggunakan IP sumber permintaan untuk mengaktifkan konektivitas ke perimeter jaringan Anda, izinkan permintaan dari rentang yang tercantum di https://www.gstatic.com/ipranges/goog.json dan tolak koneksi dari rentang yang tercantum di https://www.gstatic.com/ipranges/cloud.json (ini adalah alamat Google yang dapat digunakan untuk men-deploy workload pihak ketiga). Dialogflow tidak dapat menjamin rentang IP untuk mesin yang mengirim permintaan webhook.

Catatan: Setelah 15 Agustus 2025, agen yang diekspor tidak lagi berisi kredensial nilai mentah untuk header autentikasi, autentikasi dasar dengan nama pengguna dan sandi, atau OAuth pihak ketiga.

OAuth pihak ketiga

Dialogflow CX mengumpulkan token akses dari penyedia OAuth pihak ketiga dan menambahkannya ke header HTTP otorisasi saat membuat permintaan webhook.

Tabel berikut menjelaskan setelan resource untuk OAuth pihak ketiga:

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

Catatan: Token OAuth pihak ketiga digunakan kembali untuk permintaan webhook menggunakan client ID, URL endpoint, dan cakupan yang sama dalam agen Dialogflow CX yang sama selama permintaan dilakukan di server Dialogflow CX yang sama dan token belum habis masa berlakunya. Untuk mencapai ketersediaan tinggi, agen di-deploy di banyak server individual yang tidak berbagi cache token OAuth. Saat men-deploy solusi yang menggunakan token OAuth pihak ketiga, pertimbangkan dengan cermat untuk menerapkan proxy API guna membantu mengelola volume permintaan yang mungkin dikirim agen Anda ke penyedia OAuth pihak ketiga Anda.

Token ID agen layanan

Dialogflow CX dapat membuat token ID menggunakan agen layanan Dialogflow CX. Token ini ditambahkan ke header HTTP Otorisasi saat Dialogflow CX memanggil webhook.

Token ID dapat digunakan untuk mengakses resource Cloud Run setelah Anda memberikan peran Cloud Run Invoker (roles/run.invoker) kepada

[e-mail]

Jika resource Cloud Run berada dalam project resource yang sama, Anda tidak memerlukan izin Identity and Access Management (IAM) tambahan untuk memanggilnya.

Audiens yang digunakan untuk membuat token ID adalah seluruh URL webhook, tidak termasuk parameter kueri apa pun. Jika Anda menggunakan Cloud Run, pastikan URL ini didukung oleh audiens Cloud Run.

Misalnya, jika URL webhook adalah:

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

URL berikut harus ada di audiens kustom:

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

Webhook juga dapat secara opsional memvalidasi token menggunakan library klien Google atau library open source seperti Library Google Auth untuk Node.js.

Jika webhook Anda dihosting di Cloud Run dan diakses melalui load balancer, tambahkan URL load balancer sebagai audiens kustom ke Cloud Run Anda. Untuk mengetahui informasi selengkapnya tentang audiens kustom, lihat Menetapkan audiens kustom untuk layanan.

Akun Layanan

Akun layanan dapat digunakan untuk mengautentikasi permintaan webhook ke Google API apa pun yang mendukungnya.

Buat akun layanan jika Anda belum melakukannya.

Karena akun layanan adalah akun utama, akun layanan dapat mengakses resource dalam project Anda dengan memberinya peran, seperti akun utama lainnya. Email akun layanan digunakan untuk membuat token akses yang dikirim di header Authorization permintaan webhook.

Untuk mengonfigurasi webhook agar menggunakan akun layanan, Anda harus memiliki izin berikut:

• roles/iam.serviceAccountUser

Untuk membuat token, Agen Layanan Dialogflow harus memiliki izin berikut:

• roles/iam.serviceAccountTokenCreator

Akun layanan juga harus memiliki izin untuk mengakses layanan yang menghosting webhook.

Catatan: Jika Anda mencoba menggunakan akun layanan di beberapa project, pastikan kebijakan organisasi Anda mendukungnya. Kedua izin tersebut harus diberikan dalam proyek yang berisi akun layanan.

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:

1. Buat secret Anda jika Anda belum memilikinya.
2. Berikan peran Dialogflow Service Agent Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) pada secret baru.
3. Salin kredensial Anda ke papan klip.
4. Tambahkan versi secret baru ke secret Anda dan tempelkan kredensial Anda sebagai nilai secret:
   • 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.
5. Salin nama versi rahasia yang Anda tambahkan. Format namanya adalah projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>.
6. Buka layar edit webhook.
7. Konfigurasi setelan autentikasi:
   • Jika Anda menggunakan header autentikasi, buat header permintaan Versi secret baru. Masukkan "Authorization" di kolom Key, dan tempel nama versi rahasia ke kolom Secret version.
   • Untuk autentikasi nama pengguna dan sandi dasar, klik Versi secret di bagian Autentikasi Dasar, lalu tempel nama versi secret ke kolom Versi secret.
   • Jika Anda menggunakan OAuth Pihak Ketiga, klik Versi rahasia di bagian OAuth Pihak Ketiga, lalu tempelkan nama versi rahasia ke kolom Versi rahasia.
8. Klik Simpan.

Catatan: Kami hanya mendukung secret Secret Manager global. Kami tidak mendukung secret regional.

Verifikasi sertifikat HTTPS

Secara default, Dialogflow CX menggunakan trust store 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 produksi dari pengembangan, Anda dapat mengonfigurasi webhook agar khusus lingkungan. Anda dapat memberikan URL dan setelan autentikasi khusus lingkungan untuk setiap resource webhook.

Konfigurasi ini memungkinkan Anda mengembangkan dan menguji pembaruan kode webhook dengan aman sebelum men-deploy-nya ke produksi.

Membuat atau mengedit resource webhook

Setelah Anda menjalankan layanan webhook, buat resource webhook di agen Anda yang mencakup informasi konektivitas dan autentikasi. Anda dapat mengedit setelan resource webhook kapan saja.

Untuk membuat atau mengedit resource webhook:

Konsol

1. Buka konsol Dialogflow CX.
2. Buka project Anda.
3. Pilih agen Anda.
4. Klik tab Kelola.
5. Klik Webhook.
6. Klik Buat atau pilih webhook yang ada untuk diedit.
7. Konfigurasi setelan resource webhook standar atau setelan resource webhook fleksibel.
8. Klik Simpan.

API

Untuk mengetahui informasi tentang cara membuat resource webhook, lihat metode create untuk jenis Webhook. Untuk mengetahui informasi tentang cara mengedit resource webhook (kecuali setelan khusus lingkungan), lihat metode patch atau update untuk jenis Webhook. Buka referensi API 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

Tutup

Untuk mengetahui informasi tentang cara mengedit setelan khusus lingkungan untuk webhook, lihat metode patch atau update untuk jenis Environment. Buka referensi Environment API

Pilih protokol dan versi untuk referensi Lingkungan:

Protokol	V3	V3beta1
REST	Resource lingkungan	Resource 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

Tutup

Error webhook

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

• 400: Permintaan Buruk
• 401: Tidak sah
• 403: Dilarang
• 404: Tidak ditemukan
• 500: Kesalahan server
• 503: Layanan tidak tersedia

Dialogflow CX memanggil error webhook atau waktu tunggu peristiwa bawaan dan melanjutkan pemrosesan seperti biasa dalam situasi error berikut:

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

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 otomatis mencoba lagi permintaan pada error webhook tertentu untuk meningkatkan keandalan. Percobaan ulang otomatis diaktifkan secara default dan tidak dapat dinonaktifkan.

Dialogflow CX menjalankan satu percobaan ulang untuk kegagalan sementara, seperti waktu tunggu permintaan habis, koneksi jaringan terputus, dan kode status HTTP dalam rentang 5xx (seperti 500 Server fault atau 503 Service unavailable). Error klien terminal, seperti kode status HTTP 404 Not found, akan langsung gagal tanpa percobaan ulang.

Latensi kumulatif dan penganggaran waktu tunggu

Karena Dialogflow CX mencoba ulang kegagalan sementara satu kali, endpoint webhook yang tidak responsif dapat menyebabkan waktu penyelesaian kumulatif hingga dua kali lipat nilai waktu tunggu yang dikonfigurasi sebelum Dialogflow CX menampilkan error. Misalnya, dengan setelan waktu tunggu 5 detik default, endpoint yang tidak responsif akan mengalami waktu tunggu setelah 5 detik pada percobaan awal dan mengalami waktu tunggu setelah 5 detik lagi pada percobaan ulang. Hal ini menghasilkan total latensi sekitar 10 detik sebelum Dialogflow CX memanggil pengendali error, seperti pengendali peristiwa webhook.error.timeout atau pengendali peristiwa sys.no-match-default.

Jika arsitektur Anda memiliki batas latensi upstream yang ketat (seperti sistem respons suara interaktif (IVR) atau teleponi yang mengakhiri panggilan setelah periode tunggu 10 detik), anggarkan kedua percobaan dengan menyetel waktu tunggu webhook menjadi setengah dari periode yang diizinkan (misalnya, antara 2,5 dan 4 detik).

Praktik terbaik untuk percobaan ulang

Untuk menangani percobaan ulang secara efektif di layanan webhook Anda:

• Terapkan idempotensi atau penghapusan duplikat permintaan dalam logika layanan webhook Anda untuk memproses permintaan duplikat dengan aman.
• Jika operasi webhook Anda memerlukan waktu lebih lama dari waktu tunggu yang dikonfigurasi, segera tampilkan respons kode status HTTP 200 OK dengan pesan penggantian, dan proses tugas yang berjalan lama secara asinkron.

Menggunakan Cloud Run

Perhatian: Bagian ini menjelaskan cara menggunakan resource Cloud Run yang aman untuk webhook Dialogflow CX. Sebaiknya jaga keamanan resource Anda. Jika Anda memilih untuk melakukan autentikasi dengan nama pengguna dan sandi berbasis URL, atau header HTTP, Anda harus mengizinkan akses yang tidak diautentikasi ke resource Cloud Run Anda.

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, lalu pilih token ID dalam konfigurasi autentikasi agar agen Anda dapat memanggil webhook Anda secara aman.

Anda harus menyiapkan integrasi ini secara manual dalam dua situasi berikut:

1. Akun layanan Agen Layanan Dialogflow CX dengan alamat berikut harus ada untuk project agen Anda:

   [e-mail]

   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:
   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 Run Invoker atau Cloud Functions Invoker ke akun layanan Agen Layanan Dialogflow CX di project resource Cloud Run Anda.

Selanjutnya, pilih Service Agent Auth > ID Token di bagian Auth configuration.

Menggunakan webhook dalam container dan framework Go ezcx

Untuk menerapkan webhook dalam container menggunakan Go, lihat framework ezcx Go. Framework ini menyederhanakan banyak langkah yang diperlukan untuk membuat webhook.

Menggunakan Cloud Run dengan traffic hanya internal

Catatan: Penggunaan Cloud Run di luar perimeter Kontrol Layanan VPC project agen Dialogflow CX untuk webhook tidak didukung.

Anda dapat menggunakan resource Cloud Run yang dikonfigurasi untuk menerima traffic internal dari jaringan Virtual Private Cloud (VPC) dalam project yang sama atau perimeter Kontrol Layanan VPC yang sama sebagai webhook, asalkan agen berada dalam project yang sama atau perimeter Kontrol Layanan VPC yang sama.

Menggunakan Service Directory untuk akses jaringan pribadi

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

Untuk menyiapkan webhook yang menargetkan jaringan pribadi:

1. Ikuti konfigurasi jaringan pribadi Service Directory untuk mengonfigurasi jaringan VPC dan endpoint Service Directory.

   Catatan: Dialogflow CX menyimpan informasi Service Directory dalam cache selama 90 detik. Artinya, saat Anda memperbarui endpoint Service Directory, perubahan akan terjadi dalam waktu 90 detik.

2. Akun layanan Agen Layanan Dialogflow CX dengan alamat berikut harus ada untuk project agen Anda:

   [e-mail]

   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 di project yang berbeda dengan agen Dialogflow CX, Anda juga perlu memberikan peran servicedirectory.viewer ke akun Agen Layanan Dialogflow CX di project yang menghosting agen Dialogflow CX Anda.

3. Tentukan layanan Service Directory, URL, dan informasi autentikasi opsional saat Anda membuat webhook.

   Konsol

   

   API

   Lihat kolom serviceDirectory untuk jenis Webhook. Buka referensi API 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

   Tutup

Untuk memecahkan masalah, Anda dapat menyiapkan pemeriksaan uptime pribadi untuk memverifikasi bahwa Direktori Layanan Anda dikonfigurasi dengan benar.

Contoh dan pemecahan masalah

Untuk mengetahui informasi selengkapnya, lihat panduan cara penggunaan webhook.