סכימת POST
בקשת ה-POST שנשלחת ל-webhook תהיה בפורמט JSON עם הסכימה הבאה:
מטען ייעודי (payload) של פרוטוקול 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];
}
תיאור השדה
| שדה | תיאור | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
מחרוזת ייחודית שמזהה ליד מסוים.
המלצה לטיפול: כדאי להשתמש באפשרות הזו כדי לבטל כפילויות של לידים שמתקבלים. הערך הזה יהיה ייחודי לכל הטפסים. כשמדווחים על בעיות שקשורות לליד ספציפי, צריך לציין את המזהה הזה. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
גרסת ה-API שאליה שייכת סכימת הלידים הזו. הפרמטר הזה ישמש כשמבצעים מיגרציה לסכימה חדשה, ואפשר להתעלם ממנו כרגע. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
מזהה ייחודי לכל טופס שהוגדר ב-Google Ads. במוצר הנוכחי אפשר לצרף טופס ברמת הקמפיין (לעומת צירוף ברמת קבוצת המודעות או המודעה).
השלכות: אפשר לפלח לידים רק ברמה הלקוחות צריכים להשתמש במספר שלם של 8 בייט כדי לעבד. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
מזהה הקמפיין ב-Google Ads או מזהה הפריט (Display & Video 360) של טופס יצירת הקשר המצורף.
הלקוחות צריכים להשתמש במספר שלם באורך 8 בייט כדי לעבד את הנתונים. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
מזהה קבוצת המודעות ב-Google Ads משמש להבחנה בין קבוצות מודעות ספציפיות בקמפיין. (האפשרות זמינה רק לגבי לידים ממודעות וידאו ומודעות Discovery)
הלקוחות צריכים להשתמש במספר שלם באורך 8 בייט כדי לעבד את הנתונים. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
מזהה הקריאייטיב ב-Google Ads משמש להבחנה בין הקריאייטיבים הספציפיים בקבוצת המודעות. (האפשרות זמינה רק לגבי לידים ממודעות וידאו ומודעות Discovery)
הלקוחות צריכים להשתמש במספר שלם בגודל 8 בייט כדי לעבד את הנתונים. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
מספר הקליק ב-Google, פרמטר ייחודי שמשמש למעקב אחרי כל קליק על מודעה. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
מפתח שהמפרסם מגדיר בכל טופס.
המלצה לטיפול: לפני עיבוד ליד שהתקבל דרך webhook, מומלץ לבצע אימות של |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
השדה הזה הוא אופציונלי. אם הערך הוא true, המערכת תתייחס לליד הזה כליד לבדיקה. אם הערך הוא false או אם השדה לא קיים, המערכת תתייחס לליד הזה כאל ליד תקף בסביבת ייצור. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
טופל חוזר של צמד מפתח-ערך שמעביר נתונים שהמשתמשים סיפקו.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
השדה הזה מאוכלס רק בקמפיינים למיקסום ביצועים.
המזהה של מאגר התגים שמכיל את הטופס להשארת פרטים.
הלקוחות צריכים להשתמש במספר שלם באורך 8 בייט כדי לעבד את הנתונים. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
המאפיין הזה מציין את השלב של הליד בזמן העברת הליד. השדה הזה שימושי למעקב אחרי השלב במשפך או סטטוס ההמרה של ליד. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
חותמת הזמן שבה המשתמש שלח את הטופס. הוא מיוצג בפורמט ISO-8601. לדוגמה: 2024-09-26T12:30:00Z |
שדות לא מוכרים ותאימות קדימה
כדי לוודא שהאינטגרציה של ה-webhook תישאר חזקה ותוכל להתאים לשיפורים עתידיים, מומלץ לתכנן את מנתח ה-JSON כך שיתעלם בצורה חלקה מכל השדות במטען הייעודי (payload) של ה-webhook שהמערכת לא צורכת או מזהה באופן מפורש.
המלצה חשובה: כדאי להגדיר את הלוגיקה של ניתוח ה-JSON כך שתעבד רק את השדות שנדרשים באופן ספציפי לאפליקציה. אל תכתבו קוד שמצפה לקבוצה קבועה של שדות או שייכשל אם יש מטען ייעודי (payload) עם שדות חדשים ולא צפויים.
למה זה חשוב:
- תאימות קדימה: יכול להיות ש-Google תוסיף שדות אופציונליים חדשים למטען הייעודי (payload) של ה-webhook בעדכונים עתידיים, כדי לספק נתונים עשירים יותר או תכונות חדשות. אם הניתוח שלכם מחמיר מדי (למשל, נכשל במאפיינים לא מוכרים), יכול להיות שהשילוב שלכם ייפסק כש-Google תשיק שינויים כאלה שלא גורמים לשיבוש.
- תחזוקה פשוטה יותר: אם מתמקדים רק בנקודות הנתונים שבהן משתמשים באופן פעיל, קל יותר לתחזק את קוד השילוב.
רוב ספריות הניתוח המודרניות של JSON מציעות אפשרויות להתעלמות ממאפיינים לא מוכרים כברירת מחדל, או שאפשר להגדיר אותן כך.
טיפול בלידים
מטפלים בלידים צריכים להגיב עם קודי ה-HTTP הבאים:
| תגובת HTTP | גוף התשובה (JSON) | האם השגיאה ניתנת לתיקון? |
|---|---|---|
200 |
{} | לא רלוונטי |
4XX |
{"message: Free form error text, describing what was wrong with request"} | לא |
5XX |
{"message: Intermittent retraible error optional message"} | כן |
כפילויות
אין ערובה לכך שליד יועבר בדיוק פעם אחת, ולכן התגובה לפעולה מאתר אחר (webhook) לטיפול בלידים צריכה לטפל בכפילויות בצורה חלקה.