Ringkasan webhook

Cara Listings API mengirim peristiwa akun ke server Anda, jenis peristiwa yang tersedia, dan 5 pemeriksaan yang harus dilalui setiap pengiriman.

Melakukan polling API untuk mengetahui adanya perubahan membutuhkan banyak sumber daya dan selalu sedikit terlambat. Webhook membalik proses ini: ketika sesuatu terjadi pada akun Anda (ulasan masuk, lokasi diedit, postingan Google Business dipublikasikan), Listings API mengirim permintaan HTTP POST dengan isi JSON ke URL yang Anda kelola dalam hitungan detik.

Ada satu URL webhook per akun dan tidak ada langganan per peristiwa. Jika webhook diaktifkan untuk akun Anda dan endpoint Anda telah diverifikasi, setiap peristiwa yang tercantum di halaman ini dikirim ke satu URL tersebut. Buat percabangan berdasarkan field event dan abaikan yang tidak Anda perlukan.

Alur pengiriman

Setiap peristiwa melewati alur yang sama. Kelima persyaratan diperiksa secara berurutan, dan jika salah satunya tidak terpenuhi, tidak ada permintaan HTTP yang dibuat sama sekali, meskipun upaya tersebut tetap dicatat.

Peristiwa yang dapat Anda terima

Ada 18 peristiwa dalam enam kelompok. Masing-masing berkaitan dengan sumber daya yang sudah Anda kelola melalui REST API, sehingga webhook memberi tahu kapan perubahan terjadi dan endpoint memberi tahu apa yang berubah.

Kelompok	Peristiwa	Sumber daya REST terkait
`listing.submission`	1	Profil bisnis
`profile.*`	3: created, updated, deleted	Lokasi
`connection.*`	6: connected, disconnected, reauth, inaccessible, 2 × verifikasi Google	Akun Terhubung
`interaction.*`	2: ulasan, tanggapan	Ulasan
`local_post.*`	4: created, published, rejected, deleted	Postingan
`review_analytics.*`	2: snapshot harian dan mingguan	Analitik

Tabel field lengkap dan contoh payload tersedia di referensi peristiwa.

Di luar cakupan

Platform mengirim kelompok peristiwa lain yang tidak didokumentasikan atau didukung oleh Listings API karena tidak ada endpoint REST yang dipublikasikan untuk peristiwa tersebut di sini. Kelompok tersebut dicantumkan agar tidak terkesan ada yang terlewat:

Kampanye ulasan: campaign.*
Peringkat: rankings.*
Postingan dan promosi berbayar di Social: social_post.*
Koneksi Social: social_connection.*
Ide postingan AI: idea.*, idea_series.*, idea_pipeline.*, idea_image.*
Kepemilikan Google Business Profile: gbp_ownership.*

Dua hal yang perlu diperhatikan sebelum membangun integrasi

Prasyarat pengiriman

Pengiriman bergantung pada lima prasyarat yang diperiksa secara berurutan. Pengiriman berhenti pada prasyarat pertama yang tidak terpenuhi; prasyarat berikutnya tidak pernah diperiksa.

#	Prasyarat	Jika tidak terpenuhi
1	Paket Anda mencakup webhook. Hak akses pada akun.	Tidak ada yang dicatat. Event tidak diteruskan kepada Anda.
2	URL webhook telah dikonfigurasi pada akun.	Tidak ada yang dicatat.
3	Verifikasi endpoint berhasil: hanya diberlakukan setelah secret penandatanganan tersedia.	Dicatat sebagai `endpoint_unverified`.
4	URL dapat diresolusikan ke alamat publik (HTTPS, host yang dapat diresolusikan secara publik).	Dicatat sebagai `blocked_url`.
5	Anda masih berada dalam batas webhook paket Anda.	Dicatat sebagai `rate_limited`. Event dibuang, bukan dimasukkan ke antrean.

Paket dan batas

Webhook merupakan hak akses pada setiap paket: Launch, Growth, dan Enterprise. Masa uji coba menggunakan paket yang Anda pilih, sehingga akun uji coba memiliki akses webhook sejak hari pertama dengan batas paket tersebut. Hak akses ini melekat pada paket Anda, sehingga pemberian atau pencabutannya dilakukan sebagai bagian dari perubahan paket, bukan secara langsung: perubahan tersebut akan berlaku pada perubahan paket berikutnya atau sinkronisasi pendaftaran, bukan saat Anda mengeklik peningkatan paket. Halaman Webhooks di dasbor menampilkan hak akses dan batas yang sedang berlaku untuk Anda.

Pengiriman juga dihitung terhadap batas per menit dan per hari, yang keduanya berlaku sesuai paket Anda.

Paket	Per menit	Per hari
Launch	10	7,200
Growth	50	36,000
Enterprise	Tanpa batas	Tanpa batas

Batas webhook sama dengan batas permintaan API paket Anda: kuota event yang kami kirim kepada Anda sama dengan kuota permintaan yang Anda kirim kepada kami.

Batas baru mulai berlaku pada akun Anda setelah batas paket Anda disinkronkan ke alur pengiriman. Sebelum itu terjadi, tidak ada batas yang perlu diperiksa, sehingga tidak ada pengiriman yang dihitung terhadap batas dan tidak ada event yang dibuang. Karena itu, akun yang baru dibuat dapat menerima pengiriman tanpa penghitungan kuota sebelum batas paketnya berlaku. Jangan menganggap tidak adanya rate_limited sebagai bukti bahwa penggunaan Anda berada di bawah batas.

Cara kerja penghitungan:

Dua jendela waktu tetap yang independen: satu per menit, satu per hari. Tidak ada jendela waktu webhook per jam. (Pembatas laju permintaan merupakan sistem terpisah dengan jendela waktu yang berbeda; keduanya tidak berbagi kuota.)
Jendela waktu mengikuti kalender, bukan bergeser: penghitung per menit direset pada awal setiap menit, sedangkan penghitung harian direset pada pergantian hari UTC.
Jika batas terlampaui, event dibuang. Event tidak dimasukkan ke antrean, tidak ditunda, dan tidak dicoba ulang: tidak ada antrean percobaan ulang di bagian mana pun dalam alur pengiriman keluar, dan tidak ada pemanggil yang dapat menerima 429 sebagai respons. Upaya tersebut dicatat dengan status pengiriman rate_limited agar kehilangan event terlihat dan tidak terjadi tanpa catatan.
Jika pembatas gagal, pengiriman tetap diizinkan. Jika pembatas itu sendiri tidak dapat memberikan hasil, pengiriman tetap dilakukan dan event tidak dibuang. Anda tidak akan pernah kehilangan event akibat penghitung yang rusak.

Satu-satunya pengendalian volume bawaan pada sisi penghasil event adalah debounce pada profile.updated: maksimal satu pengiriman per lokasi per 60 detik, pada awal jendela waktu. Perubahan yang dilakukan secara cepat pada lokasi yang sama digabung menjadi satu event, dan changed_fields yang Anda terima hanya menjelaskan perubahan yang memulai jendela waktu tersebut. Tidak ada debounce pada hal lainnya.

Karena pengiriman dilakukan pada awal jendela waktu, event tiba pada awal jendela 60 detik: pembacaan ulang yang dipicu oleh kedatangannya hanya melihat perubahan pertama. Jadwalkan pembacaan ulang kedua setelah jendela waktu berakhir, setidaknya 60 detik setelah event, dan lakukan juga rekonsiliasi lokasi secara berkala, karena event itu sendiri hanya dikirim satu kali tanpa percobaan ulang. Lihat pemulihan dari event yang terlewat.

Penyiapan

Siapkan endpoint HTTPS. Endpoint harus memiliki alamat yang dapat diresolusikan secara publik dengan sertifikat yang valid, menerima POST, dan mengembalikan 2xx dalam waktu kurang dari 5 detik. Alamat privat dan internal (loopback, RFC-1918, link-local, alamat IP metadata cloud) ditolak.
Simpan URL webhook Anda di halaman Webhooks pada dasbor. Satu URL per akun untuk semua peristiwa.
Buat rahasia penandatanganan dan simpan di server Anda. Rahasia ini hanya ditampilkan sekali. Mulai saat ini, pengiriman ditandatangani dan verifikasi wajib dilakukan.
Verifikasi endpoint. Platform mengirimkan tantangan yang ditandatangani; endpoint Anda menjawab dengan HMAC dari nonce dalam format heksadesimal. Jika berhasil, status endpoint berubah menjadi terverifikasi dan pengiriman dimulai. Lihat tanda tangan dan verifikasi untuk ketentuan teknis yang tepat dan kode yang dapat dijalankan.
Tangani peristiwa. Verifikasi tanda tangan, masukkan payload ke antrean, lalu kembalikan 200. Lakukan pemrosesan utama di luar alur penanganan permintaan. Lihat perilaku pengiriman untuk batas waktu, kebijakan satu kali percobaan, serta perilaku terkait duplikasi dan urutan.

Bacaan selanjutnya

Tanda tangan dan verifikasi: header X-ListingsAPI-Signature, aturan penggunaan isi permintaan mentah, dan proses handshake.
Perilaku pengiriman: payload standar, batas waktu 5 detik, alasan tidak adanya percobaan ulang, dan setiap status pengiriman.
Referensi peristiwa: seluruh 18 peristiwa, dengan penjelasan setiap field.