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, intent yang cocok baru-baru ini, nilai parameter sesi, dan respons yang ditentukan agen semuanya disertakan.

Permintaan webhook standar

Saat fulfillment dengan webhook dipanggil, Dialogflow CX akan mengirimkan 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 menyediakan ID penelepon pengguna akhir.

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

Respons webhook standar

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

• Respons harus muncul 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 giliran percakapan secara keseluruhan. Jika waktu tunggu habis atau gagal dengan error sementara, Dialogflow CX akan otomatis mencoba lagi satu kali. Percobaan ulang ini dapat menghasilkan total waktu penyelesaian hingga dua kali lipat dari nilai waktu tunggu yang dikonfigurasi sebelum menampilkan error. Jika waktu tunggu habis setelah mencoba ulang, Dialogflow CX akan memanggil peristiwa webhook.error.timeout. Untuk mengetahui detailnya, lihat Percobaan ulang otomatis.
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.
Subjenis	Tetapkan ke Standard.
Webhook khusus lingkungan	Anda dapat menyediakan webhook khusus lingkungan.
Autentikasi	Lihat bagian Autentikasi.
Sertifikat CA kustom	Opsi ini digunakan untuk mengupload sertifikat CA kustom.

Webhook yang fleksibel

Dengan webhook fleksibel, Anda menentukan metode HTTP permintaan, parameter URL permintaan, serta kolom pesan permintaan dan respons. Permintaan hanya dapat memberikan parameter value 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 hal yang Anda butuhkan, dan Anda dapat memberikan pesan webhook unik untuk berbagai skenario.

Permintaan webhook yang 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 meng-escape URL referensi parameter atau mengapitnya dengan tanda kutip. Saat runtime, Dialogflow CX meng-escape URL parameter value sesuai kebutuhan. Daftar atau nilai gabungan disediakan sebagai JSON.

Saat menggunakan referensi parameter dalam isi JSON, Anda harus menggabungkan referensi dalam tanda kutip, terlepas dari jenis parameternya. Jika parameter tersebut sebenarnya adalah nilai skalar, daftar, atau komposit numerik, Dialogflow CX akan menghapus tanda kutip 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 direferensikan dalam nilai string (misalnya: "This is a number: $session.params.size"), parameter akan diperlakukan sebagai string ("This is a number: 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 dari respons webhook pada runtime.

Respons Anda harus memenuhi batasan berikut:

• Respons harus muncul dalam waktu tunggu yang dikonfigurasi saat membuat resource webhook, jika tidak, waktu tunggu permintaan akan habis.
• Respons harus berukuran maksimal 64 KiB.

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

$.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 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 giliran percakapan secara keseluruhan. Jika waktu upaya habis atau gagal dengan error sementara, Dialogflow CX akan otomatis mencoba lagi sekali. Percobaan ulang ini dapat menghasilkan total waktu penyelesaian hingga dua kali lipat dari nilai waktu tunggu yang dikonfigurasi sebelum menampilkan error. Jika waktu tunggu habis setelah mencoba ulang, Dialogflow CX akan memanggil peristiwa webhook.error.timeout. Untuk mengetahui detailnya, lihat Percobaan ulang otomatis.
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	Tetapkan 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
Autentikasi	Lihat bagian autentikasi.
Sertifikat CA kustom	Opsi ini digunakan untuk mengupload sertifikat CA kustom.

Menggunakan template kustom yang telah ditentukan

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

1. Buka tab Manage, pilih Webhooks, lalu klik Create.
2. Di bagian Subtype, pilih Flexible.
3. Klik Configure using predefined template.
4. Di menu Jenis integrasi, 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 diperlukan 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 menyajikan 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 Direktori layanan.
• Tangani permintaan dan respons seperti yang dijelaskan di bagian webhook standar atau webhook fleksibel.
• Jika agen Anda tidak terintegrasi dengan akses jaringan pribadi Direktori Layanan, panggilan webhook berada di luar perimeter layanan dan diblokir saat mengaktifkan Kontrol Layanan VPC. Direktori Layanan mendukung endpoint terbatas; untuk mengetahui detailnya, lihat Direktori Layanan.

Autentikasi

Amankan layanan webhook Anda sehingga hanya Anda atau agen Dialogflow CX Anda yang dapat membuat permintaan. Konfigurasikan 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 diberikan, Dialogflow CX akan menambahkan header HTTP ini ke permintaan webhook. Biasanya, satu pasangan diberikan dengan kunci authorization. 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 menggunakan Secret Manager.
Autentikasi dasar dengan nama pengguna dan sandi	Untuk setelan webhook, Anda dapat menentukan nilai nama pengguna dan sandi login opsional. Jika diberikan, 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 berikan nama pengguna dan sandi Anda 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 rahasia klien Anda menggunakan Secret Manager.
Token akses agen layanan	Tidak dilanjutkan.
Akun layanan	Anda dapat menggunakan akun layanan untuk autentikasi. Token ini dapat digunakan untuk mengakses API Google Cloud lainnya.
Token ID agen layanan	Anda dapat memilih token ID di bagian Service agent authentication, yang memungkinkan Anda menggunakan Service agent ID token 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 guna mengaktifkan konektivitas ke perimeter jaringan, 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	Rahasia yang akan digunakan saat meminta token OAuth. Sebaiknya berikan rahasia 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 dibuat 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.

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) ke

service-agent-project-number@gcp-sa-dialogflow.

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 apa pun 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 mana pun yang mendukungnya.

Buat akun layanan jika Anda belum memilikinya.

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 harus diberikan dalam project 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 secret:

1. Buat secret Anda jika Anda belum memilikinya.
2. Berikan peran Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) kepada Dialogflow Service Agent pada secret baru.
3. Salin kredensial Anda ke papan klip.
4. Tambahkan versi rahasia baru ke rahasia Anda dan tempelkan kredensial Anda sebagai nilai rahasia:
   • Jika Anda menggunakan header autentikasi, masukkan Bearer <YOUR_CREDENTIAL>.
   • Jika Anda menggunakan autentikasi nama pengguna dan sandi dasar, masukkan <YOUR_USERNAME>:<YOUR_PASSWORD>.
   • Hilangkan karakter baris baru di akhir.
5. Salin nama versi secret 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. Konfigurasikan 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 Secret version di bagian Basic Auth, lalu tempel nama versi secret ke dalam kolom Secret version.
   • 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 setelan URL dan autentikasi khusus lingkungan untuk setiap resource webhook.

Konfigurasi ini memungkinkan Anda mengembangkan dan menguji update 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 menyertakan 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 Create atau pilih webhook yang ada untuk diedit.
7. Konfigurasikan 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 untuk setelan khusus lingkungan), lihat metode patch atau update untuk jenis Webhook. Buka referensi Webhook API

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 Tidak Valid
• 401: Unauthorized
• 403: Terlarang
• 404: Tidak ditemukan
• 500: Server fault
• 503: Layanan tidak tersedia

Dialogflow CX memanggil peristiwa bawaan error atau waktu tunggu webhook 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 intent, kolom queryResult.webhookStatuses dalam respons deteksi intent akan berisi informasi status webhook.

Percobaan ulang otomatis

Dialogflow CX otomatis mencoba ulang permintaan pada error webhook tertentu untuk meningkatkan ketahanan. 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, langsung gagal tanpa percobaan ulang.

Penetapan anggaran waktu tunggu dan latensi kumulatif

Karena Dialogflow CX mencoba ulang kegagalan sementara satu kali, endpoint webhook yang tidak responsif dapat menghasilkan waktu penyelesaian kumulatif hingga dua kali lipat dari nilai waktu tunggu yang dikonfigurasi sebelum Dialogflow CX menampilkan error. Misalnya, dengan setelan waktu tunggu default 5 detik, endpoint yang tidak responsif akan mengalami waktu tunggu setelah 5 detik pada upaya awal dan mengalami waktu tunggu setelah 5 detik lagi pada upaya 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 telepon atau tanggapan suara interaktif (IVR) yang menghentikan panggilan setelah jendela waktu tunggu 10 detik), anggarkan untuk kedua upaya dengan menetapkan waktu tunggu webhook ke setengah dari jendela 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 dalam project yang sama dengan agen, pilih Service Agent Auth, lalu pilih token ID dalam konfigurasi autentikasi agar agen dapat memanggil webhook Anda dengan 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:

   service-agent-project-number@gcp-sa-dialogflow.

   Akun layanan khusus ini dan kunci terkait biasanya dibuat secara otomatis saat Anda membuat agen pertama untuk sebuah 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 Dialogflow CX Service Agent di project resource Cloud Run Anda.

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

Menggunakan webhook dalam container dan framework ezcx Go

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 khusus 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 Direktori Layanan untuk akses jaringan pribadi

Dialogflow CX terintegrasi dengan akses jaringan pribadi Direktori Layanan, sehingga dapat terhubung ke target webhook di dalam jaringan VPC Anda. Hal ini menjaga traffic tetap berada 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 jaringan VPC dan endpoint Direktori Layanan Anda.

   Catatan: Dialogflow CX meng-cache informasi Direktori Layanan selama 90 detik. Artinya, saat Anda memperbarui endpoint Direktori Layanan, perubahan akan memerlukan waktu 90 detik untuk diterapkan.

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

   service-agent-project-number@gcp-sa-dialogflow.

   Berikan peran berikut ke akun layanan Dialogflow CX Service Agent di project tempat Direktori Layanan Anda berada:

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   Selain itu, jika Direktori Layanan Anda berada dalam project yang berbeda dengan agen Dialogflow CX, Anda juga harus memberikan peran servicedirectory.viewer ke akun Agen Layanan Dialogflow CX dalam project yang menghosting agen Dialogflow CX Anda.

3. Tentukan layanan Direktori Layanan, URL, dan informasi autentikasi opsional apa pun saat Anda membuat webhook.

   Konsol

   

   API

   Lihat kolom serviceDirectory untuk jenis Webhook. Buka referensi Webhook API

   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 cek uptime pribadi untuk memverifikasi bahwa Direktori Layanan Anda dikonfigurasi dengan benar.

Contoh dan pemecahan masalah

Untuk mengetahui informasi selengkapnya, lihat panduan cara kerja webhook.