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.
Rekomendasi penanganan: Gunakan ini untuk menghapus duplikat prospek yang diterima. ID ini akan unik di semua formulir. Saat melaporkan masalah yang terkait dengan prospek tertentu, ID ini akan diperlukan. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
Versi API tempat skema prospek ini berada. 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
lampiran formulir dengan tingkat kampanye (bukan lampiran di tingkat grup iklan atau iklan
itu sendiri).
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 yang dilampirkan.
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.
Menangani rekomendasi: Sebelum memproses prospek yang diterima melalui
webhook, memvalidasi |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
Kolom ini memiliki semantik "opsional". Jika nilainya benar, perlakukan prospek ini sebagai prospek pengujian. Jika nilainya salah atau jika kolom tidak ada, anggap prospek ini sebagai prospek produksi yang valid. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
Tupel nilai kunci berulang yang mengirimkan data yang dikirimkan pengguna.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
Kolom ini hanya diisi untuk kampanye Performa Maksimal.
Ini 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. Format ini direpresentasikan dalam format ISO-8601. Contoh: 2024-09-26T12:30:00Z |
Kompatibilitas mundur dan kolom yang tidak dikenal
Untuk memastikan integrasi webhook Anda tetap andal dan dapat beradaptasi dengan peningkatan mendatang, praktik terbaik standarnya adalah mendesain parser JSON untuk mengabaikan kolom apa pun dalam payload webhook yang tidak digunakan atau dikenali secara eksplisit oleh sistem Anda.
Rekomendasi Utama: Konfigurasikan logika penguraian JSON Anda agar hanya memproses kolom yang secara khusus Anda perlukan untuk aplikasi Anda. Jangan menulis kode yang mengharapkan kumpulan kolom tetap atau yang akan gagal jika kolom baru yang tidak terduga ada dalam payload.
Alasan pentingnya hal ini:
- Kompatibilitas Maju: Google dapat menambahkan kolom opsional baru ke payload webhook dalam update mendatang untuk memberikan data yang lebih lengkap atau fitur baru. Jika PARSER terlalu ketat (misalnya, gagal pada properti yang tidak diketahui), integrasi Anda dapat rusak saat perubahan yang tidak merusak tersebut diluncurkan oleh Google.
- Pemeliharaan yang Disederhanakan: Dengan hanya berfokus pada titik data yang Anda gunakan secara aktif, kode integrasi Anda akan 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
Pengendali 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 prospek tidak dijamin akan dikirim tepat satu kali, sehingga webhook penanganan prospek harus menangani duplikat dengan baik.