Implementierung

POST-Schema

Die an den Webhook gesendete POST-Anfrage hat das folgende JSON-Format:

Webhook-Protonutzlast

// 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];
}

Feldbeschreibung

Feld	Beschreibung
lead_id	Eindeutiger String, der einen bestimmten Lead identifiziert. Empfehlung zur Verarbeitung:Verwenden Sie diese Option, um empfangene Leads zu deduplizieren. Dieser Wert ist für alle Formulare eindeutig. Wenn Sie Probleme im Zusammenhang mit einem bestimmten Lead melden, ist diese ID erforderlich.
api_version	Die API-Version, zu der dieses Lead-Schema gehört. Diese wird bei der Migration zu einem neuen Schema verwendet und kann vorerst ignoriert werden.
form_id	Eindeutige ID für jedes in Google Ads konfigurierte Formular. Im aktuellen Produkt ist es möglich, ein Formular auf Kampagnenebene anzuhängen (im Gegensatz zu Anzeigengruppen- oder Anzeigenebene). Auswirkungen:Leads können nur auf form_id-Ebene (d.h. auf Kampagnenebene) segmentiert werden. Clients müssen 8-Byte-Ganzzahlen für die Verarbeitung verwenden.
campaign_id	Die Google Ads-Kampagnen-ID oder die Werbebuchungs-ID (Display & Video 360) des angehängten Lead-Formulars. Clients müssen einen 8‑Byte-Integer verwenden, um die Daten zu verarbeiten.
adgroup_id	Die Google Ads-Anzeigengruppen-ID wird verwendet, um die jeweilige Anzeigengruppe in der Kampagne zu unterscheiden. (Nur für Leads aus Video- und Discovery-Anzeigen verfügbar) Clients müssen einen 8‑Byte-Integer verwenden, um die Daten zu verarbeiten.
creative_id	Mit der Google Ads-Creative-ID wird das jeweilige Creative in der Anzeigengruppe unterschieden. (Nur für Leads aus Video- und Discovery-Anzeigen verfügbar) Clients müssen einen 8‑Byte-Integer verwenden, um die Daten zu verarbeiten.
gcl_id	Google Click ID: Ein eindeutiger Parameter, mit dem jeder Klick auf eine Anzeige erfasst wird.
google_key	Ein Schlüssel, der vom Werbetreibenden für jedes Formular konfiguriert wird. Empfehlung:Bevor Sie einen Lead verarbeiten, der über einen Webhook empfangen wurde, sollten Sie google_key mit der Konfiguration in Google Ads abgleichen, um sicherzugehen, dass der Lead gültig ist. Bewahren Sie diesen Schlüssel vertraulich auf und aktualisieren Sie ihn in Google Ads, wenn Sie Grund zur Annahme haben, dass er weit verbreitet wurde.
is_test	Dieses Feld ist optional. Wenn der Wert „true“ ist, wird dieser Lead als Test-Lead behandelt. Wenn „value“ „false“ ist oder das Feld nicht vorhanden ist, wird dieser Lead als gültiger Produktions-Lead behandelt.
user_column_data	Ein wiederholtes Schlüssel/Wert-Tupel, das vom Nutzer übermittelte Daten überträgt. user_column_data.column_id: Der vom Nutzer eingereichte Datentyp. User_column_data.column_value: Für jeden Datentyp wird ein Wertetyp angegeben, der vom Datentyp abhängt. Alle unsere aktuellen Datentypen haben den Wert user_column_data.string_value. user_column_data.column_name: Für Menschen lesbarer Text des vom Nutzer eingereichten Datentyps. Dieses Feld wird möglicherweise nicht immer ausgefüllt. Verwenden Sie stattdessen column_id . user_column_data.column_id Inhalt von User_column_data.string_value user_column_data.column_name (eingestellt) „FULL_NAME“ Vollständiger Name des Nutzers. „Vollständiger Name“ „FIRST_NAME“ Vorname des Nutzers „Vorname“ „LAST_NAME“ Nachname des Nutzers „Nachname“ „EMAIL“ E-Mail-Adresse des Nutzers „E-Mail-Adresse des Nutzers“ „PHONE_NUMBER“ Telefonnummer des Nutzers im E.164-Format, z.B. "[phone]". „User Phone“ „PHONE_NUMBER_VERIFIED“ Gibt an, ob die Telefonnummer des Nutzers bestätigt wurde. „Telefonnummer bestätigt“ „POSTAL_CODE“ Postleitzahl des Nutzers. „Postleitzahl“ „COMPANY_NAME“ Name des Unternehmens des Nutzers. „Name des Unternehmens“ „JOB_TITLE“ Die Position des Nutzers. „Job Title“ (Berufsbezeichnung) „WORK_EMAIL“ Die Arbeits-E-Mail-Adresse des Nutzers. „Arbeits-E-Mail“ „WORK_PHONE“ Geschäftliche Telefonnummer des Nutzers. „Arbeitstelefon“ „STREET_ADDRESS“ Straße und Hausnummer des Nutzers. „Adresse“ „CITY“ Wohnort des Nutzers „Stadt“ „REGION“ Region des Nutzers. „Region“ „COUNTRY“ Land des Nutzers. „Land“ „VEHICLE_MODEL“ Für welches Modell interessieren Sie sich? – „VEHICLE_TYPE“ Für welchen Fahrzeugtyp interessieren Sie sich? – „PREFERRED_DEALERSHIP“ Bevorzugten Händler auswählen – „VEHICLE_PURCHASE_TIMELINE“ Wann möchten Sie ein Fahrzeug kaufen? – „VEHICLE_CONDITION“ Welchen Zustand soll das Fahrzeug haben? – „VEHICLE_OWNERSHIP“ Besitzt du ein Fahrzeug? „–“ „VEHICLE_PAYMENT_TYPE“ Welche Form der Fahrzeugfinanzierung interessiert Sie? – „COMPANY_SIZE“ Wie groß ist Ihr Unternehmen? – „ANNUAL_SALES“ Wie hoch ist Ihr Jahresumsatz? – „YEARS_IN_BUSINESS“ Wie lange sind Sie schon im Geschäft? – „JOB_DEPARTMENT“ In welcher Abteilung arbeiten Sie? – „JOB_ROLE“ Welchen Beruf üben Sie aus? – „EDUCATION_PROGRAM“ Für welches Programm interessieren Sie sich? – „EDUCATION_COURSE“ Für welchen Kurs interessieren Sie sich? – „PRODUCT“ Für welches Produkt interessieren Sie sich? – „SERVICE“ Welche Dienstleistung interessiert Sie? – „OFFER“ Für welches Angebot interessieren Sie sich? – „CATEGORY“ Für welche Kategorie interessieren Sie sich? – „PREFERRED_CONTACT_METHOD“ Bevorzugte Methode zur Kontaktaufnahme auswählen – „PREFERRED_LOCATION“ Bevorzugten Standort auswählen – „PREFERRED_CONTACT_TIME“ Wann sind Sie am besten zu erreichen? – „PURCHASE_TIMELINE“ Wann möchtest du etwas kaufen? – "YEARS_OF_EXPERIENCE" Wie viele Jahre Berufserfahrung haben Sie? – „JOB_INDUSTRY“ In welcher Branche sind Sie tätig? – „LEVEL_OF_EDUCATION“ Was ist Ihr höchster Bildungsabschluss? – „PROPERTY_TYPE“ Nach welcher Art von Immobilie suchen Sie? – „REALTOR_HELP_GOAL“ Wobei soll Ihnen ein Makler helfen? – „PROPERTY_COMMUNITY“ Welche Immobilienart interessiert Sie? – „PRICE_RANGE“ Für welche Preisspanne interessieren Sie sich? – „NUMBER_OF_BEDROOMS“ Wie viele Schlafzimmer möchten Sie? – „FURNISHED_PROPERTY“ Bist du auf der Suche nach einer voll möblierten Immobilie? – „PETS_ALLOWED_PROPERTY“ Suchen Sie nach Immobilien, in denen Haustiere erlaubt sind? – „NEXT_PLANNED_PURCHASE“ Welches Produkt möchten Sie als Nächstes kaufen? – „EVENT_SIGNUP_INTEREST“ Möchten Sie sich für eine Veranstaltung registrieren? – „PREFERRED_SHOPPING_PLACES“ Wo würden Sie einkaufen? – „FAVORITE_BRAND“ Was ist Ihre Lieblingsmarke? – "TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" Welche Art von gültiger gewerblicher Lizenz haben Sie? – „EVENT_BOOKING_INTEREST“ Möchten Sie eine Veranstaltung buchen? – „DESTINATION_COUNTRY“ Was ist Ihr Zielland? – „DESTINATION_CITY“ Was ist Ihr Zielort? – „DEPARTURE_COUNTRY“ Was ist Ihr Abreiseland? – „DEPARTURE_CITY“ Was ist Ihr Abreiseort? – „DEPARTURE_DATE“ Wann reisen Sie ab? – „RETURN_DATE“ Wann reisen Sie zurück? – „NUMBER_OF_TRAVELERS“ Mit wie vielen Personen reisen Sie? – „TRAVEL_BUDGET“ Wie hoch ist Ihr Reisebudget? – „TRAVEL_ACCOMMODATION“ Wo möchten Sie während der Reise übernachten? –
asset_group_id	Dieses Feld wird nur für Performance Max-Kampagnen ausgefüllt. Dies ist die Container-ID, die das Lead-Formular enthält. Clients müssen einen 8‑Byte-Integer verwenden, um die Daten zu verarbeiten.
lead_stage	Dies ist die Lead-Phase zum Zeitpunkt der Lead-Übermittlung. Dieses Feld ist hilfreich, um die Trichterphase bzw. den Conversion-Status eines Leads zu verfolgen.
lead_submit_time	Dies ist der Zeitstempel, zu dem der Nutzer das Formular gesendet hat. Sie wird im ISO-8601-Format dargestellt. Beispiel: 2024-09-26T12:30:00Z

Nicht erkannte Felder und Vorwärtskompatibilität

Damit Ihre Webhook-Integration stabil bleibt und sich an zukünftige Verbesserungen anpassen kann, ist es eine bewährte Standardmethode, Ihren JSON-Parser so zu gestalten, dass er alle Felder in der Webhook-Nutzlast, die Ihr System nicht explizit verwendet oder erkennt, problemlos ignoriert.

Wichtiger Hinweis:Konfigurieren Sie die Logik für das JSON-Parsing so, dass nur die Felder verarbeitet werden, die Sie für Ihre Anwendung benötigen. Schreiben Sie keinen Code, der eine feste Gruppe von Feldern erwartet oder fehlschlägt, wenn neue, unerwartete Felder in der Nutzlast vorhanden sind.

Warum das wichtig ist:

• Vorwärtskompatibilität:Google kann dem Webhook-Payload in zukünftigen Updates neue, optionale Felder hinzufügen, um umfangreichere Daten oder neue Funktionen bereitzustellen. Wenn Ihr Parser zu streng ist (z.B. bei unbekannten Eigenschaften fehlschlägt), kann Ihre Integration unter Umständen nicht mehr funktionieren, wenn solche nicht schwerwiegenden Änderungen von Google eingeführt werden.
• Vereinfachte Wartung:Wenn Sie sich nur auf die Datenpunkte konzentrieren, die Sie aktiv verwenden, bleibt Ihr Integrationscode einfacher und lässt sich leichter warten.

Die meisten modernen JSON-Parsing-Bibliotheken bieten Optionen, um unbekannte Eigenschaften standardmäßig zu ignorieren. Sie können auch so konfiguriert werden, dass sie dies tun.

Lead-Bearbeitung

Lead-Handler sollten mit den folgenden HTTP-Codes antworten:

HTTP-Antwort	Antworttext (JSON)	Wiederholbarer Fehler?
200	{}	–
4XX	{"message: Free form error text, describing what was wrong with request"}	Nein
5XX	{"message: Intermittent retraible error optional message"}	Ja

Duplikate

Es kann nicht garantiert werden, dass ein einzelner Lead genau einmal zugestellt wird. Daher sollte der Webhook für die Lead-Verarbeitung Duplikate problemlos verarbeiten können.

Wichtiger Hinweis :Verwenden Sie lead_id, um Leads zu deduplizieren.