• Trust
  • Anfrage einreichen

    • Need assistance with your Emarsys product?
    We'll get you the help you need!

     

    Emarsys client

     

    Emarsys client
    SAP for Me Login

    You can contact our support team via the SAP for Me.

    The Emarsys component: CEC-EMA

    		Login to the Help Portal and Submit your request. 
    1. Emarsys
    2. Automatisierung
    3. Automation programs

    Nodes:: Webhook-Knoten
    Aktualisiert

    Wichtig: Beim Webhook-Knoten handelt es sich um eine komplexere Funktion. Um sie in Ihre Applikation(en) integrieren zu können, müssen Sie über die entsprechenden technischen Ressourcen verfügen; zudem liegt es in Ihrer Verantwortung, dafür zu sorgen, dass der integrierte Dienst ordnungsgemäß funktioniert.

    Mit dem Webhook-Knoten konfigurieren Sie Webhooks für die Verwendung in Automation Programmen. Damit ermöglichen Sie die Kommunikation zwischen Emarsys und anderen Customer Experience Lösungen. Mit Webhooks können Sie Daten zu Ihrem externen System oder Ihrer externen Applikation senden, wenn ein Kontakt in einem Interactions Programm oder Automation Center Programm den Webhook-Knoten erreicht.

    Seiten mit verwandten Themen:

    Voraussetzungen

    • Nur Nutzer, die Editor-Berechtigungen bzgl. der Voreinstellungen für Webhook-Knoten haben, können Voreinstellungen für Webhook-Knoten erstellen, bearbeiten oder löschen. Wenn Sie diese Aktionen nicht ausführen können, kontaktieren Sie bitte Ihren Account Owner. Die Benutzerberechtigungen können Sie auf der Seite Management > Benutzermanagement überprüfen.
    • Sie müssen über ein externes System oder eine externe Lösung verfügen, die das von Emarsys gesendete Event empfangen kann (wir senden die Events via POST API Requests). Events werden im JSON-Format gesendet und die Struktur der Kontaktdaten und zusätzlichen Daten besteht aus einem einzigen Level. Optional können Sie auch Eventdaten-Attribute senden, die unter dem Objekt event_data (also im zweiten Level der Hierarchie) gelistet sind. Ein Beispiel:
    { "event_time": "2021-04-01T17:08:44Z", "email_address": "example@emarsys.com"   "event_data": {         "event_time": "2021-04-01T17:05:11Z",         "order_id": 4534322,         "Order_status": "shipped" }, "scenario": "shipping_update" }
    Für Kopieren klicken
    • Optionale Voraussetzung, wenn Ihre Sicherheitsmaßnahmen die Verwendung einer Allowlist erfordern: Der Webhook-Knoten stellt die Verbindung zu Ihrer Customer Experience Lösung über bestimmte IP-Adressen her. Damit der Knoten mit Ihrer Lösung kommunizieren kann, müssen Sie die folgenden IP-Adressen zu Ihrer Allowlist hinzufügen:
      • 34.89.173.3
      • 35.246.249.205
      • 34.89.137.140

    Use Cases

    Rabatte in Ihrem externen System übernehmen

    Nehmen wir an, ein Kontakt erreicht in Ihrer Emarsys Automation Journey jenen Punkt, an dem er Anspruch auf einen Rabatt hat. Bevor der Kontakt den Rabatt erhalten kann, müssen Sie Folgendes tun:

    • Sie müssen diese Aktion in Ihrem externen Service aufzeichnen, um den Rabatt für den jeweiligen Kunden zu übernehmen, und
    • Sie müssen das Event zwischen Emarsys und Ihrem externen System synchronisieren.

    In diesem Fall können Sie Kontaktdaten (z.B. die E-Mail-Adresse des Kontakts) und zusätzliche Daten (z.B. aus welchem Szenario der Kontakt kommt und auf welchen Rabatt er Anspruch hat) mit dem Webhook-Knoten an Ihren externen Service senden.

    Kontakte mit einer externen Loyalty-Lösung synchronisieren

    Der Webhook-Knoten kann nützlich sein, wenn Sie eine externe Loyalty-Lösung haben und jene Kontakte damit synchronisieren wollen, die sich für das Emarsys Loyalty-Programm qualifiziert haben.

    Emarsys mit Offline-Kanälen verbinden

    Auch wenn Sie Emarsys mit Ihren Offline-Kanälen verbinden wollen (z.B. mit Verteilungszentren, in denen personalisierte Geschenke zum Versandgut hinzugefügt werden und Direktmail-Lösungen verwendet werden), kann der Webhook-Knoten nützlich sein.

    Voreinstellung für Webhook-Knoten erstellen

    Um eine Voreinstellung für den Webhook-Knoten zu erstellen, gehen Sie wie folgt vor:

    1. Navigieren Sie zu Automation > Voreinstellungen für Webhook-Knoten und klicken Sie Voreinstellung vornehmen.

    2. Konfigurieren Sie das Erscheinungsbild des Webhook-Knotens:

    a. Geben Sie den Namen der Voreinstellung ein.

    b. Wählen Sie ein Knoten-Icon aus. Standardmäßig wird das Icon für den API-Knoten verwendet.

    Um zu überprüfen, wie Ihr Knoten aussieht, wählen Sie die Voreinstellung in der Knoten-Vorschau aus.

    3. Konfigurieren Sie die Verbindung.

    Bitte beachten Sie, dass Sie mit dem Webhook-Knoten keine Verbindungen zu den Endpunkten des api.emarsys.net herstellen können.

    a. Geben Sie die API Endpunkt URL Ihres externen Service oder Ihrer externen Applikation an.

    Hinweise:

    • Sie müssen eine sichere URL angeben, die mit dem Präfix https:// beginnt.
    • Bitte verwenden Sie keine URLs, die auf einen der Emarsys Endpunkte verweisen.
    • Falls der Request fehlschlägt, unternimmt das Programm automatisch mehrere weitere Verbindungsversuche; dabei werden die Pausen zwischen den Versuchen immer länger: die erste Pause dauert 30 Sekunden, die letzte 10 Minuten. Nach dem 11. fehlgeschlagenen Versuch geht das Programm in den Fail-safe-Modus über. Wenn Sie verhindern wollen, dass das Programm bei kleinen Fehlern in den Fail-Safe-Modus versetzt wird, müssen Sie sicherstellen, dass der Fehler 406 zurückgegeben wird. In diesem Fall werden die Kontakte verworfen, das Programm läuft jedoch weiter.

    b. Wählen Sie die Authentifizierungsmethode aus. Folgende Methoden sind verfügbar:

    - HTTP Basic Authentifizierung - Wenn Sie diese Methode auswählen, müssen Sie Ihren Benutzernamen und Ihr Passwort angeben.

    - JWT-Authentifizierung - Wenn Sie diese Methode auswählen, müssen Sie Ihren Secret Key angeben.

    - OAuth2 - Wenn Sie diese Methode auswählen, müssen Sie die Authentifizierungs-URL, Client-ID, das Client-Secret und den Bereich (optional) angeben.

    4. Definieren Sie die Event Payload. Die Payload des Webhook-Knotens kann Daten des triggernden Events, Werte aus Kontaktdatenfeldern und zusätzliche Daten mit statischen Werten enthalten.

    a. Triggernde Eventdaten senden - Wählen Sie diese Checkbox aus, wenn Sie die Event Payload weiterleiten wollen, die das Programm triggert.

    Hinweise:

    • Attribute von Eventdaten werden unter dem Objekt event_data gelistet.
    • Bitte beachten Sie, dass die Eventdaten-Feldzuordnung nicht verfügbar ist.
    • Eventdaten enthalten keine Metadaten, nur Attribute, die in Interactions über den Knoten Entscheidung gefiltert werden können. Das bedeutet, dass die Eventdaten, die dieselben Attribute enthalten, an den konfigurierten Endpunkt (der das Programm getriggert hat) gesendet werden - ohne zusätzliche Daten und unabhängig von den Knoten, die das Trigger Event durchlaufen hat.
    • Wenn Sie die Checkbox Triggernde Eventdaten senden aktivieren und diese Voreinstellung in einem Programm ohne Event Payload verwenden (wenn z.B. das externe Event, welches das Programm triggert, keine Payload enthält, oder in wiederkehrenden Automation Center Programmen), dann ist das Objekt event_data leer.

    b. Kontaktdaten - Hier können Sie Key/Wert-Paare für das Senden von Werten aus Kontaktdatenfeldern definieren:

    - Um ein neues Feld hinzuzufügen, klicken Sie + Feld hinzufügen.

    - Um ein Key/Wert-Paar zu löschen, klicken Sie das Löschen-Icon.

    Hinweise:

    c. Zusätzliche Daten - Diese Felder können statische Werte enthalten, die mit den Requests gesendet werden, damit Ihr externes System deren Quelle identifizieren kann (z.B. die Journey oder das Szenario, aus denen das Event kommt), ebenso wie den Zweck (z.B. informiert ein Unternehmen, das Direktmails druckt, ob für den jeweiligen Kontakt das Willkommensprogramm oder eine Kampagne für abwandernde Kunden gedruckt werden soll).

    Um ein neues Feld hinzuzufügen, klicken Sie + Feld hinzufügen. Um ein Feld zu entfernen, klicken Sie das Icon.

    Sie können mehrere zusätzliche Felder zur Payload hinzufügen. Diese befinden sich auf demselben hierarchischen Level wie Kontaktfelder.

    Hier können Sie Folgendes definieren:

    • Feldname - Der Feld/Key-Name, der in der Payload aufscheint.
    • Feldtyp - Sie können aus folgenden Typen wählen: Text, Numerisch oder Boolesch.
    • Vordefinierte Werte - Das Hinzufügen von Werten zu Feldern ist optional. Nachdem Sie einen Wert eingegeben haben, klicken Sie Hinzufügen. Sie können aus folgenden Optionen wählen:
      • Wenn Sie keinen vordefinierten Wert eingeben, ist nach dem Auswählen der Voreinstellung in einer Journey ein Eingabefeld im Knoten verfügbar; in diesem Feld kann jeder Wert eingegeben werden, der dem ausgewählten Typ entspricht.
      • Wenn Sie nur einen Wert spezifizieren, enthält die Payload immer diesen Wert, der auch im Webhook-Knoten in der Automation Journey nicht geändert werden kann; das ist nützlich, wenn Sie System-IDs an das externe System senden wollen, um erkennen zu können, woher ein Request stammt.
      • Wenn Sie mehrere vordefinierte Werte hinzufügen, können die Nutzer den Wert aus dem Dropdown im Webhook-Knoten auswählen, der in der Payload gesendet wird.

    In diesem Fall sehen Marketer im Webhook-Knoten folgende Optionen:

    d. Betriebsdaten - Optionale Eventdatenfelder, die standardmäßig zum Webhook Payload Request hinzugefügt werden. Sie können die Auswahl dieser Felder aufheben und sie umbenennen.

    Um sicherzustellen, dass das empfangende System keine duplizierten Nachrichten verarbeitet, empfehlen wir die Verwendung des Feldes deduplication_ID.

    Sie können aus folgenden Feldern wählen:

    - deduplication_id - UUID, mit dem die Verarbeitung doppelter Nachrichten vermieden wird.

    - ems_program_id - Die ID des Programms, in dem der Webhook-Knoten getriggert wurde.

    - event_time - Die Timestamp, die angibt, wann der Webhook-Knoten getriggert wurde.

    5. Um die Verbindung und Authentifizierung zu testen und eine Vorschau der vom Programm gesendeten Daten anzuzeigen, klicken Sie Test starten.

    Wenn Sie testen wollen, wie Ihr Programm die Eventdaten sendet, erstellen Sie ein Programm, das vom entsprechenden Event getriggert wird.

    Hier können Sie:

    • Datenvorschau anzeigen - Um die Daten einzusehen, geben Sie die E-Mail-Adresse des Kontakts ein und klicken Sie Datenvorschau anzeigen.

    Hinweise:

    • Sie können eine Vorschau der Daten anzeigen und die Verbindung testen, ohne die Voreinstellung zu speichern. Das ist nützlich, wenn die Voreinstellung bereits in aktiven Programmen verwendet wird und Sie die Aktualisierungen testen wollen, bevor Sie die Änderungen abschließen.
    • Das Feld event_data field enthält ein leeres Objekt, da sein Content stark von dem Programm abhängig ist, in dem der Knoten verwendet wird. Wenn Sie den Request mit der Event Payload testen wollen, empfehlen wir, das Programm zu testen.
    • Ein beliebiger Wert, der dem ausgewählten Typ entspricht, wird für folgende Felder erstellt:
      • deduplication_id
      • ems_program_id
      • additional data
    • Verbindung testen - Sie können die Verbindung testen, indem Sie Ihren Endpunkt mit den Vorschaudaten triggern. Diese Option ist nur verfügbar, nachdem die Datenvorschau angezeigt wurde. Weitere Informationen zu den Statuscodes erhalten Sie unter Response Codes. Hier sehen Sie Folgendes:
      • Status: Der Response Code, der vom Endpunkt empfangen wurde.
      • Response: Der Response Body.
      • Datenvorschau: Die Payload, die an den Endpunkt gesendet wurde (einsehbar im Schritt Datenvorschau anzeigen).

    Webhook-Knoten in einem Automation Programm verwenden

    1. Öffnen Sie das Programm an der Stelle, an der Sie den Webhook-Knoten verwenden wollen, und fügen Sie diesen ein.

    2. Doppelklicken Sie den Webhook-Knoten und wählen Sie aus dem Dropdown die erforderliche Voreinstellung aus. Nachdem Sie die Voreinstellung ausgewählt haben, werden das Icon und der Name des Knotens entsprechend aktualisiert.

    3. Hier sehen Sie alle Daten, die in der ausgewählten Voreinstellung konfiguriert sind.

    Hinweise:

    • Wenn Sie ein Feld hinzufügen oder entfernen wollen, müssen Sie die Voreinstellung ändern. Bitte beachten Sie, dass für das Ändern von Voreinstellungen für Webhook-Knoten die Bererchtigungen ??? erforderlich sind. Wenn Sie Voreinstellungen nicht ändern können, kontaktieren Sie Ihren Account Owner.
    • Voreinstellungen, die in aktiven oder fertiggestellten Programmen verwendet werden, können nicht geändert werden. In diesen Fällen müssen Sie die Programme anhalten oder einfrieren, um die Voreinstellung zu ändern.
    • Eventdaten - Hier sehen Sie den Status der Evendaten. Der Status kann wie folgt sein:
      • Es werden keine Daten des triggernden Events gesendet - Das Programm sendet keine Daten des triggernden Events.
      • Daten des triggernden Events werden gesendet - Das Programm sendet Daten des triggernden Events.
    • Kontaktdaten - Die Liste der Key/Wert-Paare, die mit den Werten der ausgewählten Kontaktdatenfeldern gesendet werden.
    • Zusätzliche Daten - Sie müssen die statischen Werte auswählen oder eingeben, die für jeden verarbeiteten Kontakt gesendet werden.

    So sieht ein Webhook-Knoten aus:

    Voreinstellungen für Webhook-Knoten verwalten

    Ihre Voreinstellungen für Webhook-Knoten werden auf der Seite Automation > Voreinstellung für Webhook-Knoten gelistet.

    Hier können Sie:

    • Eine Voreinstellung für Webhook-Knoten erstellen, indem Sie Voreinstellung vornehmen klicken.
    • Eine Voreinstellung kopieren, indem Sie klicken.
    • Eine Voreinstellung bearbeiten, indem Sie klicken.
    • Eine Voreinstellung löschen, indem Sie klicken.

    Response Codes

    Fehlgeschlagene Zustellversuche können dazu führen, dass Programme in den Fail-safe-Modus versetzt oder Kontakte aus Programmen ausgeschlossen werden. Kontakte, die das Programm am Webhook-Knoten verlassen haben, werden auf der Seite Programm-Reporting als Ausgeschieden geführt.

    Response Code Als "empfangen" gekennzeichnet Ergebnis
    20x (success) Ja Die Applikation hat die vom Webhook-Knoten gesendeten Daten empfangen.
    30x (redirection) Nein Fehlgeschlagene Requests werden wiederholt; nach dem 11. fehlgeschlagenen Versuch wird das Programm in den Fail-safe-Modus versetzt. Emarsys folgt der Umleitung nicht.
    406 (not acceptable) Nein Der Kontakt verlässt das Programm.
    408 (request timeout) Nein Fehlgeschlagene Requests werden wiederholt; nach dem 11. fehlgeschlagenen Versuch wird das Programm in den Fail-safe-Modus versetzt.
    429 (rate limited) Nein Fehlgeschlagene Requests werden wiederholt; nach dem 11. fehlgeschlagenen Versuch wird das Programm in den Fail-safe-Modus versetzt.
    Other 4xx (client error) Nein Fehlgeschlagene Requests werden wiederholt; nach dem 11. fehlgeschlagenen Versuch wird das Programm in den Fail-safe-Modus versetzt.
    5xx (server error) Nein Fehlgeschlagene Requests werden wiederholt; nach dem 11. fehlgeschlagenen Versuch wird das Programm in den Fail-safe-Modus versetzt.

    Bekannte Probleme und Einschränkungen

    • Vom Webhook-Knoten gesendete Requests werden nach 20 Sekunden beendet, d.h. wenn der externe Endpunkt nicht innerhalb dieser Frist antwortet, schlägt der Request fehl.
    • Der Webhook-Knoten sendet einen Request nach dem anderen (er sendet nicht in Batches). Wenn Sie zum Beispiel 1.000 Events senden wollen, enthält ein Request jeweils 1 Event oder 1 Kontakt.
    • Bevor Sie Events für eine größere Anzahl von Kontakten senden, bedenken Sie bitte, dass dies eine Weile dauern kann. Wenn Sie den Webhook-Knoten zum Beispiel in einem Automation Center Programm mit einer 100.000 Kontakte starken Kontaktliste verwenden, wird für jeden Kontakt 1 Request gesendet; Kontakte können die Journey erst fortsetzen, nachdem alle Responses für alle Kontakte aus dem externen System empfangen wurden.
    • Bitte stellen Sie sicher, dass Ihr externes System gut darauf vorbereitet ist, eine so große Anzahl an Events zu empfangen (das System also in der Lage ist, die Load zu verarbeiten, und diese nicht als DDoS-Attacke einstuft).
    • Wenn Sie den Webhook-Knoten zu Interactions Programmen hinzufügen, bedenken Sie bitte Folgendes: Emarsys kann nicht garantieren, dass die Interactions SLA immer erfüllt werden, weil wir nach dem Senden jedes Events auf den Response des externen Systems warten müssen.

    Seiten mit verwandten Themen: