Skema POST
Permintaan POST yang dikirim ke webhook akan dalam format JSON dengan skema berikut:
Payload Proto Webhook
// Represent user lead data for single column
message UserLeadColumnData {
// Human-readable text of the field type (e.g.: Full Name, What is your
// preferred dealership?). This field might not always be populated.
optional string column_name = 1;
// Column value based on column type
oneof column_value {
string string_value = 2;
}
// Column ID. Populated for all types of fields. (e.g.: FULL_NAME)
optional string column_id = 3;
}
// Message to construct webhook JSON payload
message WebhookLead {
// Unique ID to represent lead
optional string lead_id = 1;
// User inputted data per column
repeated UserLeadColumnData user_column_data = 2;
// API version
optional string api_version = 3;
// Form ID to which lead belonged to.
optional int64 form_id = 4;
// Campaign ID that the lead form is associated with
optional int64 campaign_id = 5;
// Key to be used by advertiser to verify the request
// is from Google.
optional string google_key = 6;
// Denotes if the lead is a test lead.
optional bool is_test = 7;
// Click ID for the lead submission.
optional string gcl_id = 8;
// Adgroup ID which generated the lead.
optional int64 adgroup_id = 9;
// Creative ID which generated the lead.
optional int64 creative_id = 10;
// Asset group ID represents the container for holding assets, associated
// URLs, hints and criteria that will be used to select assets and for
// optimization. This field is only populated for Performance Max campaigns.
int64 asset_group_id = 11;
// Lead stage at the time of delivery.
string lead_stage = 12 [(datapol.semantic_type) = ST_NOT_REQUIRED];
// Lead submit time in ISO-8601 format. Ex- 2024-09-26T12:30:00Z
string lead_submit_time = 13 [(datapol.semantic_type) = ST_NOT_REQUIRED];
}
Deskripsi kolom
| Kolom | Deskripsi | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
String unik yang mengidentifikasi prospek tertentu.
Penanganan rekomendasi: Gunakan ini untuk menghapus duplikat prospek yang diterima. ID ini akan unik di semua formulir. Saat melaporkan masalah terkait prospek tertentu, ID ini akan diperlukan. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
Versi API yang memiliki skema prospek ini. Ini akan digunakan saat bermigrasi ke skema baru, dan dapat diabaikan untuk saat ini. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
ID unik untuk setiap formulir yang dikonfigurasi di Google Ads. Produk saat ini memungkinkan
melampirkan formulir dengan tingkat kampanye (vs. melampirkan di tingkat grup iklan atau iklan).
Implikasi: Prospek hanya dapat dikelompokkan di tingkat Klien harus menggunakan bilangan bulat 8 byte untuk diproses. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
ID kampanye Google Ads atau ID item baris (Display & Video 360) dari
formulir prospek terlampir.
Klien harus menggunakan bilangan bulat 8 byte untuk diproses. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
ID grup iklan Google Ads digunakan untuk membedakan grup iklan tertentu dalam kampanye. (Hanya tersedia untuk prospek dari iklan video dan Discovery)
Klien harus menggunakan bilangan bulat 8 byte untuk diproses. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
ID materi iklan Google Ads digunakan untuk membedakan materi iklan tertentu dalam grup iklan. (Hanya tersedia untuk prospek dari iklan video dan Discovery)
Klien harus menggunakan bilangan bulat 8 byte untuk diproses. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
ID klik Google, parameter unik yang digunakan untuk melacak setiap klik iklan. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
Kunci yang dikonfigurasi oleh pengiklan dengan setiap formulir.
Penanganan rekomendasi: Sebelum memproses prospek yang diterima melalui webhook, validasi |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
Kolom ini memiliki semantik "opsional". Jika nilainya benar, perlakukan prospek ini sebagai prospek pengujian. Jika nilai salah (false) atau jika kolom tidak ada, perlakukan prospek ini sebagai prospek produksi yang valid. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
Tuple nilai kunci berulang yang mengirimkan data yang dikirimkan pengguna.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
Kolom ini hanya diisi untuk kampanye Performa Maksimal.
Menunjukkan ID penampung yang berisi formulir prospek.
Klien harus menggunakan bilangan bulat 8 byte untuk diproses. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
Ini menunjukkan tahap prospek pada saat pengiriman prospek. Kolom ini berguna dalam melacak tahap funnel / status konversi prospek. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
Ini menunjukkan stempel waktu saat pengguna mengirimkan formulir. Direpresentasikan dalam format ISO-8601. Ex- 2024-09-26T12:30:00Z |
Kolom yang tidak dikenal dan kompatibilitas ke depan
Untuk memastikan integrasi webhook Anda tetap kuat dan dapat beradaptasi dengan peningkatan di masa mendatang, praktik terbaik standar adalah mendesain parser JSON Anda agar mengabaikan dengan baik semua kolom dalam payload webhook yang tidak secara eksplisit digunakan atau dikenali oleh sistem Anda.
Rekomendasi Utama: Konfigurasi logika penguraian JSON Anda agar hanya memproses kolom yang secara khusus Anda perlukan untuk aplikasi Anda. Jangan menulis kode yang mengharapkan sekumpulan kolom tetap atau yang akan gagal jika ada kolom baru yang tidak terduga dalam payload.
Mengapa hal ini penting:
- Kompatibilitas ke Depan: Google dapat menambahkan kolom baru yang bersifat opsional ke payload webhook dalam update mendatang untuk memberikan data yang lebih kaya atau fitur baru. Jika parser Anda terlalu ketat (misalnya, gagal pada properti yang tidak diketahui), integrasi Anda dapat terganggu saat perubahan tidak merusak tersebut diluncurkan oleh Google.
- Pemeliharaan yang Disederhanakan: Dengan hanya berfokus pada titik data yang aktif Anda gunakan, kode integrasi Anda tetap lebih sederhana dan lebih mudah dikelola.
Sebagian besar library penguraian JSON modern menawarkan opsi untuk mengabaikan properti yang tidak diketahui secara default atau dapat dikonfigurasi untuk melakukannya.
Penanganan prospek
Penangan prospek harus merespons dengan kode HTTP berikut:
| Respons HTTP | Isi respons (JSON) | Error yang dapat dicoba lagi? |
|---|---|---|
200 |
{} | T/A |
4XX |
{"message: Free form error text, describing what was wrong with request"} | Tidak |
5XX |
{"message: Intermittent retraible error optional message"} | Ya |
Duplikat
Satu lead tidak dijamin akan dikirimkan tepat satu kali, sehingga webhook penanganan lead harus menangani duplikat dengan baik.