Zum Inhalt springen

Webhook

Mit Webhooks können Sie Journey-Daten an externe Dienste wie Analyse-, CRM-Systeme und Marketing-Tools senden. Sie können:

  • Externe Systeme benachrichtigen, wenn ein Kunde eine Aktion in der Journey ausführt
  • Kundendaten an Analyse-Tools senden
  • E-Mails, SMS oder WhatsApp von Drittanbietern bei bestimmten Journey-Ereignissen auslösen

So richten Sie das Webhook-Element ein

Anchor link to

Fügen Sie das Webhook-Element hinzu

Anchor link to

Ziehen Sie das Webhook-Element per Drag-and-Drop auf die Arbeitsfläche. Platzieren Sie den Webhook an einer beliebigen Stelle und berücksichtigen Sie dabei, welche Journey-Informationen Sie an einen Drittanbieterdienst senden möchten.

Customer Journey-Arbeitsfläche mit einem ausgewählten Amplitude-Webhook-Schritt nach den Eingangs- und Warteelementen

Benennen Sie den Webhook-Schritt und geben Sie die Anfrage-URL und den Typ an

Anchor link to

Geben Sie im Feld STEP NAME einen Namen für den Webhook ein. Es kann praktisch sein, Webhooks nach den Diensten, an die sie Daten senden, oder nach dem Anwendungsfall zu benennen.

Geben Sie als Nächstes im Feld URL die Anfrage-URL an, an die die Daten gesendet werden sollen. Wählen Sie neben dem URL-Feld den Anfragetyp aus dem Dropdown-Menü REQUEST TYPE aus: GET oder POST.

Webhook-Konfigurationsoberfläche mit URL-Feld und REQUEST TYPE-Dropdown zur Auswahl der GET- oder POST-Methode

Konfigurieren Sie die Header

Anchor link to

Legen Sie im Abschnitt HEADERS den Inhaltstyp fest.

Standardmäßig ist der Inhaltstyp application/json. Wenn der Dienst, an den Sie den Webhook senden, einen anderen Inhaltstyp erfordert, geben Sie den entsprechenden Wert im Content-Type-Header ein.

Beispiele für Inhaltstypen sind:

  • x-www-form-urlencoded
  • text/plain
  • text/xml

Fügen Sie bei Bedarf zusätzliche Header hinzu, indem Sie auf + ADD HEADER klicken. Sie können jeden Header entfernen, indem Sie auf das ‘x’-Symbol daneben klicken.

Fügen Sie den Authentifizierungs-Header hinzu, den Ihr Endpunkt benötigt, zum Beispiel:

  • Authorization: Bearer <token>
  • X-Api-Key: <key>
  • Authorization: Basic <base64(user:pass)>

Es wird nur ein statisches Geheimnis in einem Header unterstützt. OAuth2-Token-Austausch-Flows, mTLS und das Signieren von Anfragen auf der Pushwoosh-Seite werden nicht unterstützt. Sie können den Endpunkt auch auf die IP-Adressen von Pushwoosh beschränken, anstelle von oder zusätzlich zu einem Header-Geheimnis. Siehe Pushwoosh-IP-Adressen.

Speziell für die HTTP-Basic-Authentifizierung gehen Sie wie folgt vor:

  1. Öffnen Sie einen einfachen Texteditor und geben Sie Ihren Benutzernamen und Ihr Passwort ohne Leerzeichen ein, getrennt durch einen Doppelpunkt. Zum Beispiel: <username>:<password>
  2. Kodieren Sie diese Zeichenfolge in Base64.
  3. Kopieren Sie die resultierende Base64-Zeichenfolge (zum Beispiel <base64-encoded-string>).
  4. Fügen Sie in den Webhook-Einstellungen einen Authorization-Header mit dem Wert hinzu: Basic <base64-encoded-string>. Stellen Sie sicher, dass nach dem Wort „Basic“ ein Leerzeichen steht.
Beispiel für einen Authorization-Header für die Basic-Authentifizierung in den Webhook-Einstellungen, der Content-Type- und Authorization-Header anzeigt

Einen Header-Wert als geheim markieren

Anchor link to

Klicken Sie auf das Augensymbol neben dem Wert eines Headers, um ihn zu maskieren. Pushwoosh verbirgt diesen Wert überall dort, wo er den Dienst sonst verlassen würde: in der Benutzeroberfläche, in API-Antworten und im Versionsverlauf der Journey.

Liste der Webhook-Header mit einem maskierten Authorization-Wert und einem deaktivierten Augensymbol neben einem nicht maskierten Content-Type-Wert mit einem aktiven Augensymbol
  • Automatische Maskierung. Header, deren Namen wie Anmeldeinformationen aussehen, werden automatisch maskiert, auch wenn Sie nie auf das Augensymbol klicken. Dazu gehören Authorization, Proxy-Authorization, Cookie, Set-Cookie und jeder Name, der token, secret, password, credential, auth oder api-key/api_key/apikey enthält (mit einem Bindestrich, einem Unterstrich oder ohne Trennzeichen).
  • Einen maskierten Wert ändern. Klicken Sie in das Feld, das •••••••• anzeigt, und geben Sie den neuen Wert ein. Es gibt keine Schaltfläche, um den gespeicherten Wert anzuzeigen. Das Augensymbol bleibt gesperrt, während die Maske angezeigt wird. Um das Geheimnis-Flag von einem Header zu entfernen, geben Sie zuerst einen neuen Wert ein und klicken Sie dann auf das Symbol.
  • Einen maskierten Header umbenennen. Das Umbenennen eines Headers, dessen Wert derzeit als Maske angezeigt wird, löscht diesen Wert. Geben Sie ihn unter dem neuen Namen erneut ein. Das Umbenennen eines Headers, der derzeit einen gerade eingegebenen Wert enthält, behält diesen Wert bei.

Fügen Sie den JSON-Anfrage-Body hinzu

Anchor link to

Geben Sie im Abschnitt DATA Ihren JSON-Anfrage-Body ein. Stellen Sie sicher, dass der Anfrage-Body im korrekten JSON-Format ist.

Beispiel:

{
"hwid": "{{device:hwid}}"
}

Verwenden Sie dynamische Daten und Makros

Anchor link to

Das DATA BUILDER-Panel ermöglicht es Ihnen, dynamische Informationen (wie Benutzer-, Geräte-, Tag- oder Ereignisdaten) direkt in Ihren JSON-Anfrage-Body einzufügen. Mit Dynamic Data können Sie Werte einschließen, die für den einzelnen Benutzer spezifisch sind, der die Journey durchläuft.

Dazu:

  1. Wählen Sie eine Kategorie aus. Sie können Daten aus drei Kategorien abrufen:
  • Device: Verwenden Sie Gerätedaten, wenn Sie technische Informationen benötigen, die an das Gerät des Benutzers gebunden sind.

  • Tag: Verwenden Sie Tag-Daten, wenn Sie im Benutzerprofil gespeicherte Informationen senden möchten.

  • Event: Verwenden Sie Ereignisdaten, wenn der Webhook Werte aus dem auslösenden Ereignis der Journey senden soll.

  1. Wählen Sie einen Parameter aus (zum Beispiel HWID, Lieblingskategorie usw.).
  2. Pushwoosh generiert ein Makro, das wie folgt aussieht:
{{tag:Language}}
  1. Kopieren Sie das Makro und fügen Sie es in Ihren JSON-Body im DATA-Abschnitt ein.

Wenn der Webhook in einer Live-Journey ausgeführt wird, ersetzt Pushwoosh das Makro automatisch durch den tatsächlichen Wert für diesen Benutzer.

Dynamische Datenplatzhalter in den Webhook-Anfrage-Body einfügen

Zusätzliche Platzhalter manuell eingeben

Anchor link to

Ein Platzhalter ist ein Makro, das Sie von Hand eingeben, anstatt es aus einer DATA BUILDER-Kategorie zu generieren. Das DATA BUILDER-Panel deckt nur Device-, Tag- und Event-Daten ab. Geben Sie diese Platzhalter stattdessen direkt in die Abschnitte URL, HEADERS oder DATA ein. Sie erscheinen nicht im Panel:

PlatzhalterWert
{{application_code}}Der Anwendungscode der App, zu der der Reisende gehört.
{{traveler:id}}Die ID, die Pushwoosh diesem Reisenden für diesen Journey-Lauf zuweist.
{{journey:uuid}}Die UUID dieser Journey.
{{journey:name}}Der Name dieser Journey.
{{point:uuid}}Die UUID dieses Webhook-Schritts.
{{point:name}}Der STEP NAME dieses Webhook-Schritts.
{{event:name}}Der Name des Ereignisses, das den Eintritt dieses Reisenden in die Journey ausgelöst hat.
{{device:platform}}Die Plattform des Geräts, zum Beispiel Android oder iOS.
{{device:push_subscribed}}Ob der Reisende für Push-Benachrichtigungen angemeldet ist — true oder false.
{{now}}Das aktuelle Datum und die Uhrzeit, ISO 8601, UTC.
{{now:unix_ms}}Die aktuelle Zeit als Unix-Millisekunden.
{{tags:all}}Jeder Tag-Wert für das Gerät des Reisenden als ein JSON-Objekt. Verwenden Sie es ohne Anführungszeichen, zum Beispiel "user_properties": {{tags:all}}. Wenn Sie es in Anführungszeichen setzen, wird das Objekt stattdessen in eine escapete Zeichenfolge umgewandelt.

Den Typ eines Platzhalters im JSON-Body beibehalten

Anchor link to

Ein Platzhalter in Anführungszeichen wird immer zu einer JSON-Zeichenfolge, unabhängig vom tatsächlichen Typ des Werts. Derselbe Platzhalter allein, ohne Anführungszeichen, behält stattdessen den eigenen Typ des Werts bei: eine Zahl bleibt eine Zahl, true/false bleibt ein boolescher Wert und eine Liste wird zu einem JSON-Array. Ein Platzhalter ohne Anführungszeichen muss der gesamte Wert des Feldes sein — "age": {{tag:Age}} funktioniert, aber "note": prefix{{tag:Age}}suffix nicht, da alles außerhalb der Anführungszeichen genau wie eingegeben geschrieben wird und die zusätzlichen Zeichen das JSON beschädigen.

{
"age": {{tag:Age}},
"age_as_text": "{{tag:Age}}"
}

Hier sendet age den numerischen Wert des Tags (34), während age_as_text die Zeichenfolge "34" sendet. Verwenden Sie das, was das empfangende Feld erwartet. Wenn der Tag keinen Wert hat, wird ein Platzhalter ohne Anführungszeichen immer noch zu einer leeren Zeichenfolge aufgelöst, nicht zu einer Zahl oder false. Siehe den Hinweis unter Fügen Sie den JSON-Anfrage-Body hinzu.

Webhook-Antwortdaten Variablen zuordnen

Anchor link to

Neben dem Senden von Daten kann der Webhook-Schritt auch Werte aus der Antwort Ihres Dienstes behalten. Sie geben jedem Wert einen Namen (Attribut). Spätere Schritte können diesen Namen auf die gleiche Weise verwenden wie andere Webhook-Antwortwerte. Setzen Sie zum Beispiel ein Tag mit Benutzerprofil aktualisieren oder planen Sie eine Zeitverzögerung ab einem vom Dienst zurückgegebenen Datum. Ein vollständiges Journey-Beispiel finden Sie unter Verwendung von Webhook-Antwortdaten in Ihrer Journey.

Beispiel: Das CRM gibt eine Benutzer-ID zurück. Sie speichern sie als Attribut crm_user_id. Dann schreibt Benutzerprofil aktualisieren sie in ein Tag.

Bevor Sie etwas zuordnen, holen Sie sich eine Beispielantwort vom Dienst. Fragen Sie Ihren Entwickler oder öffnen Sie nach einem Test einen erfolgreichen Anruf im Anrufprotokoll und sehen Sie sich den Antwort-Body an. Sie benötigen die Feldnamen aus dieser Antwort, um den Pfad zu erstellen.

Klicken Sie im Abschnitt RESPONSE MAPPING auf + ADD MAPPING und füllen Sie für jeden Wert, den Sie erfassen möchten, zwei Felder aus:

  • Pfad: der Speicherort des Werts im JSON-Antwort-Body, mit Punkten zwischen den Ebenen
  • Attribut: der Name, den Sie später in der Journey verwenden werden
Abschnitt für die Antwortzuordnung mit den Feldern Pfad und Attribut und der Schaltfläche Zuordnung hinzufügen in den Webhook-Einstellungen

Wenn Ihr CRM zum Beispiel mit Folgendem antwortet:

{
"data": {
"user": {
"id": "789xyz"
}
}
}
  1. Setzen Sie den Pfad auf data.user.id.
  2. Setzen Sie das Attribut auf crm_user_id.

Nachdem ein Benutzer diesen Schritt durchlaufen hat, können spätere Elemente das Attribut crm_user_id auf die gleiche Weise auswählen wie andere Webhook-Antwortwerte.

Bedingte Aufteilung kann sie nicht direkt verwenden. Zugeordnete Webhook-Werte haben keinen Typ. Speichern Sie den Wert zuerst als Tag und verzweigen Sie dann auf dieses Tag. Siehe Einen Webhook-Wert in der bedingten Aufteilung vergleichen.

Für ein einzelnes Feld funktionieren Pfad und Werte wie folgt:

Jedes Element eines Arrays zuordnen

Anchor link to

Manchmal hat eine Webhook-Antwort nicht nur einen Wert. Sie hat eine Liste, wie jedes Produkt in einer Bestellung, jeder Artikel in einem Warenkorb oder jedes Ergebnis einer Suche. Die Antwortzuordnung erfasst normalerweise einen Wert pro Feld, sodass Sie ohne dies nur einen zugeordneten Wert aus dieser Liste erhalten würden und der Rest verloren ginge.

Setzen Sie * in das Pfad-Feld, wo sich die Liste befindet. Pushwoosh holt sich dann einen Wert von jedem Element in der Liste, nicht nur von einer Position. Wenn die Liste zum Beispiel items heißt und jedes Element item_name hat, setzen Sie den Pfad auf items.*.item_name.

Klicken Sie in RESPONSE MAPPING auf + ADD MAPPING und füllen Sie die beiden Felder wie gewohnt aus, wobei * die Liste markiert:

  • Pfad: der Speicherort des Werts in der Antwort, mit * an der Stelle der Liste. Beispiel: items.*.item_name.
  • Attribut: der Name, den Sie später verwenden werden. Was Sie hier schreiben, entscheidet darüber, wie Sie die Ergebnisse zurückerhalten:
    • Fügen Sie {n} in den Namen ein, zum Beispiel item_{n}, um jedes Element als eigenen Wert zu erhalten, nummeriert ab 1: item_1, item_2, item_3 und so weiter. {n} kann an jeder Stelle im Namen stehen, zum Beispiel item_{n}_sku.
    • Lassen Sie {n} weg, zum Beispiel item_names, um jedes Element zu einem einzigen Wert zusammenzufügen, getrennt durch Kommas: Sofa, Lampe, Teppich.
Zeile für die Antwortzuordnung mit Pfad auf items.*.item_name und Attribut auf item_{n} gesetzt

Die Positionen in der Pfadliste beginnen bei 0 (items.0.item_name ist das erste Element). Attributnamen, die mit {n} erstellt werden, beginnen bei 1 (item_1 ist dieses erste Element). Dies sind zwei verschiedene Nummerierungen.

Wenn Sie nur ein Element aus der Liste benötigen, verwenden Sie eine Zahl im Pfad anstelle von *, zum Beispiel items.0.item_name.

Wenn Ihr CRM mit Folgendem antwortet:

{
"items": [
{ "item_name": "Sofa" },
{ "item_name": "Lamp" },
{ "item_name": "Rug" }
]
}
  • Setzen Sie den Pfad auf items.*.item_name und das Attribut auf item_{n}, um drei separate Werte zu erhalten: item_1 ist Sofa, item_2 ist Lampe, item_3 ist Teppich.
  • Setzen Sie stattdessen das Attribut auf item_names, um einen Wert zu erhalten: item_names ist Sofa, Lampe, Teppich.

Sie können die zugeordneten Werte später in der Journey wie jedes andere Webhook-Antwortattribut verwenden:

Bedingte Aufteilung kann sie nicht direkt verwenden. Zugeordnete Webhook-Werte haben keinen Typ. Speichern Sie den Wert zuerst als Tag und verzweigen Sie dann auf dieses Tag. Siehe Einen Webhook-Wert in der bedingten Aufteilung vergleichen.

Timeout, Wiederholungsversuche und fehlgeschlagene Anfragen

Anchor link to

Pushwoosh wartet bis zu 10 Sekunden auf eine Antwort. Der gesamte Webhook-Schritt, einschließlich des Sendens der Anfrage und der Verarbeitung der Antwort, ist auf 30 Sekunden begrenzt.

Wiederholungsversuche

Anchor link to

Bei einer 500, 502, 503 oder 504-Antwort oder einem Netzwerkfehler wie einem Verbindungsfehler versucht Pushwoosh die Anfrage einmal erneut, bevor sie aufgegeben wird. Eine Anfrage, die ein Timeout hat, wird nicht erneut versucht — siehe Was passiert, wenn eine Anfrage fehlschlägt unten. Jede andere Nicht-2xx-Antwort wird ebenfalls nicht erneut versucht.

Ratenbegrenzungen

Anchor link to

Pushwoosh begrenzt, wie viele Webhook-Anfragen ein Konto pro Sekunde senden kann. Das Limit ist deutlich über den realen Verkehrsspitzen angesetzt, sodass normale Journeys nicht betroffen sind. Ein Burst, der es überschreitet, wartet kurz auf Kapazität, bevor er fehlschlägt.

Endpunkt-Abklingzeit

Anchor link to

Wenn ein Endpunkt mehrmals hintereinander fehlschlägt, hört Pushwoosh für eine Weile auf, Anfragen an ihn zu senden, anstatt einen defekten Endpunkt bei jedem Reisenden erneut zu versuchen. Dies beginnt bei 30 Sekunden und verdoppelt sich bei weiteren Fehlschlägen auf bis zu 5 Minuten. Eine einzige erfolgreiche Anfrage hebt dies auf und setzt die normale Zustellung fort.

Was passiert, wenn eine Anfrage fehlschlägt

Anchor link to

Das Webhook-Element hat keinen separaten Zweig für fehlgeschlagene Anfragen. Jedes der folgenden Ereignisse lässt den Reisenden an diesem Schritt aus der Journey ausscheiden:

UrsacheWas löst es aus
Blockierte EndpunktadresseDie URL ist privat, intern, Loopback oder Link-Local, einschließlich Cloud-Metadaten-Endpunkten
RatenbegrenzungDas pro-Sekunde-Webhook-Anfragelimit des Kontos wird überschritten und während der kurzen Wartezeit wird kein Platz frei
Endpunkt-AbklingzeitDer Endpunkt ist mehrmals hintereinander fehlgeschlagen und Pushwoosh überspringt ihn vorübergehend
TimeoutKeine Antwort innerhalb von 10 Sekunden, oder der Schritt überschreitet seine 30-Sekunden-Grenze
NetzwerkfehlerDie Anfrage konnte den Endpunkt überhaupt nicht erreichen
Nicht-2xx-AntwortDer Endpunkt hat einen Fehlerstatus zurückgegeben, der nicht erneut versucht wird, oder wurde einmal erneut versucht und ist wieder fehlgeschlagen

Siehe Anfragefehler.

Wenn Sie es sich nicht leisten können, hier Reisende zu verlieren, lassen Sie Ihren Endpunkt immer eine 2xx-Antwort zurückgeben und legen Sie jeden Fehlerzustand stattdessen in den Antwort-Body, zum Beispiel als einen Wert, den Ihre Antwortzuordnung aufgreifen kann.

Dies gilt für jeden Webhook-Schritt, einschließlich der früher erstellten. Eine Endpunktadresse, die jetzt der oben genannten Regel für blockierte Adressen entspricht, wird auf die gleiche Weise fehlschlagen.

Im Gegensatz zu einer fehlgeschlagenen Anfrage führt eine Antwort, die ankommt, aber nicht sauber zugeordnet werden kann, wie z. B. ungültiges JSON, ein nicht aufgelöster Pfad oder ein Body über 64 KB, nicht dazu, dass der Reisende ausscheidet. Siehe den Hinweis unter Antwortzuordnung oben.

Testen Sie den Webhook

Anchor link to

Klicken Sie auf Webhook testen, um zu überprüfen, ob Ihre Webhook-Konfiguration korrekt ist und die Anfrage erfolgreich gesendet wird.

Wenn ein Header immer noch die gespeicherte Maske anzeigt, füllt Pushwoosh den echten, gespeicherten Wert für die Testanfrage ein. Der Wert erscheint niemals in Ihrem Browser.

Diese Ersetzung funktioniert nur für einen Header, der bereits in genau diesem Schritt gespeichert wurde. Ein Schritt, den Sie noch nicht gespeichert haben, oder einer, den Sie gerade kopiert haben, hat keinen gespeicherten Wert hinter der Maske, daher sendet Pushwoosh die Testanfrage ohne diesen Header.

Öffnen Sie nach einem erfolgreichen Test (oder einem Live-Anruf) das Anrufprotokoll, erweitern Sie die Zeile und vergleichen Sie den Antwort-Body mit jedem Pfad. Das Feld muss genau wie im Pfad existieren. Wenn die Anfrage erfolgreich ist, aber ein späterer Schritt keinen Wert hat, stimmt der Pfad normalerweise nicht mit der Antwort überein. Der Webhook-Schritt zeigt dafür keinen Fehler an.

Speichern Sie Ihre Konfiguration

Anchor link to

Klicken Sie auf Speichern, um Ihre Webhook-Konfiguration zu speichern.

Anrufprotokoll

Anchor link to

Öffnen Sie den Tab Anrufprotokoll in der Schublade des Punktes, um zu sehen, was Pushwoosh für diesen Schritt tatsächlich gesendet hat: Zeit, Benutzer, Ergebnis und Dauer, bis zu 30 Tage zurück.

Filtern Sie nach Ergebnis (Erfolg, HTTP-Fehler, Keine Antwort) oder suchen Sie nach der genauen Benutzer-ID oder HWID. Klicken Sie auf eine Zeile, um sie zu erweitern und die Anfrage (Methode, URL und Body) und, je nach Ergebnis, entweder die Antwort (Status und Body) oder den Fehlertext zu sehen. Die Dauer umfasst den gesamten Schritt, einschließlich der Zeit, die für einen automatischen Wiederholungsversuch aufgewendet wurde.