Eine Webhook-Kampagne erstellen

Durch das Erstellen einer Webhook-Kampagne oder das Einbinden eines Webhooks in eine Multichannel-Kampagne können Sie Nicht-App-Aktionen auslösen, indem Sie anderen Systemen und Anwendungen Echtzeitinformationen bereitstellen.

Sie können Webhooks verwenden, um Informationen an Systeme wie Salesforce oder Marketo oder an Ihre Backend-Systeme zu senden. Beispielsweise möchten Sie möglicherweise die Konten Ihrer Kund:innen mit einer Aktion gutschreiben, nachdem sie ein angepasstes Event eine bestimmte Anzahl von Malen ausgeführt haben.

Tipp

Um mehr darüber zu erfahren, was Webhooks sind und wie Sie sie in Braze verwenden können, lesen Sie Webhooks, bevor Sie fortfahren.

Schritt 1: Wählen Sie, wo Sie Ihre Nachricht erstellen möchten

Sind Sie unsicher, ob Ihre Nachricht über eine Campaign oder einen Canvas gesendet werden soll? Campaigns eignen sich besser für einzelne, gezielte Messaging-Kampagnen, während Canvases besser für mehrstufige User-Journeys geeignet sind.

• campaign
• canvas

Schritte:

1. Gehen Sie zu Messaging > Campaigns und wählen Sie Campaign erstellen.
2. Wählen Sie Webhook oder für Campaigns, die auf mehrere Kanäle abzielen, Multichannel.
3. Geben Sie Ihrer Campaign einen eindeutigen und aussagekräftigen Namen.
4. (Optional) Fügen Sie eine Beschreibung hinzu, um zu erläutern, wie diese Campaign verwendet wird.
5. Fügen Sie nach Bedarf Teams und Tags hinzu.
   • Tags erleichtern das Auffinden Ihrer Campaigns und das Erstellen von Berichten. Wenn Sie beispielsweise den Berichts-Builder verwenden, können Sie nach bestimmten Tags filtern.
6. Fügen Sie so viele Varianten hinzu und benennen Sie sie, wie Sie für Ihre Campaign benötigen. Sie können für jede hinzugefügte Variante unterschiedliche Webhook-Templates auswählen. Weitere Informationen zu diesem Thema finden Sie unter Multivariate und A/B-Tests.

Tipp

Wenn alle Nachrichten in Ihrer Campaign ähnlich sein oder denselben Inhalt haben werden, verfassen Sie Ihre Nachricht, bevor Sie weitere Varianten hinzufügen. Anschließend können Sie im Dropdown Variante hinzufügen die Option Von Variante kopieren auswählen.

Schritte:

1. Erstellen Sie Ihr Canvas mit dem Canvas-Composer.
2. Nachdem Sie Ihr Canvas eingerichtet haben, fügen Sie im Canvas-Builder einen Schritt hinzu. Geben Sie Ihrem Schritt einen klaren und aussagekräftigen Namen.
3. Wählen Sie einen Schritt-Zeitplan und legen Sie bei Bedarf eine Verzögerung fest.
4. Filtern Sie die Zielgruppe für diesen Schritt nach Bedarf. Sie können die Empfänger:innen dieses Schritts weiter eingrenzen, indem Sie Segmente angeben und zusätzliche Filter hinzufügen. Die Zielgruppenoptionen werden nach der Verzögerung zum Zeitpunkt des Nachrichtenversands überprüft.
5. Wählen Sie Ihr Fortschrittsverhalten.
6. Wählen Sie alle weiteren Messaging-Kanäle, die Sie mit Ihrer Nachricht kombinieren möchten.

Schritt 2: Webhook erstellen

Sie können einen Webhook von Grund auf neu erstellen, ein vorhandenes Template verwenden oder eines unserer bestehenden Templates nutzen. Erstellen Sie dann Ihren Webhook im Tab Erstellen des Editors.

Der Tab Erstellen besteht aus den folgenden Feldern:

• Sprachen
• Webhook-URL
• HTTP-Methode
• Anfrage-Body

Sprachen

Sie können einen Webhook mithilfe von mehrsprachigen Nachrichten an Nutzer:innen in mehreren Märkten senden. Die Übersetzung wird im Anfrage-Body und in der Webhook-URL unterstützt.

So lokalisieren Sie einen Webhook:

1. Erstellen Sie die Locales, die Sie in Ihrem Workspace unterstützen möchten.
2. Umschließen Sie im Tab Erstellen nur den Text, der übersetzt werden soll, mit Übersetzungs-Tags. Zum Beispiel: {% translation greeting %}Hello!{% endtranslation %}.
3. Wählen Sie Sprachen verwalten, wählen Sie Ihre Locales aus und fügen Sie Übersetzungen hinzu, indem Sie eine CSV-Datei hochladen oder die Übersetzungs-API verwenden.
4. Wählen Sie Mehrsprachige:r Nutzer:in aus dem Dropdown Vorschau als Nutzer:in, um jedes Locale vor dem Senden in der Vorschau anzuzeigen.

Wichtig

Umschließen Sie nur für Menschen lesbare Werte mit Übersetzungs-Tags. Niemals JSON-Schlüssel, Klammern, Kommas oder andere Strukturelemente. Übersetzer:innen könnten Sonderzeichen ändern oder entfernen, was zu einem fehlerhaften Anfrage-Body führen kann, den Ihr Endpunkt ablehnt.

Für einen Anfrage-Body, der mit JSON-Schlüssel-Wert-Paaren erstellt wurde, taggen Sie nur den Wert:

1
2
3

{
  "message_body": "{% translation order_ready %}Your order just arrived!{% endtranslation %}"
}

URL lokalisieren

Wenn sich Ihr Endpunkt je nach Markt unterscheidet, können Sie Teile der URL mit Übersetzungs-Tags umschließen. Lassen Sie das Protokoll (https://) außerhalb der Tags und fügen Sie keine Abfrageparameter innerhalb der Tags ein. Weitere Informationen finden Sie unter URLs lokalisieren.

Webhook-Templates

Webhook-Templates unterstützen gespeicherte Übersetzungen, sodass Sie ein Template einmal lokalisieren und in Campaigns und Canvas-Schritten wiederverwenden können. Sie benötigen die Berechtigung Edit Webhook Templates, um Locales und Übersetzungen zu einem Template hinzuzufügen. Siehe Webhook-Templates.

Webhook-URL

Die Webhook-URL, oder HTTP-URL, gibt Ihren Endpunkt an. Der Endpunkt ist der Ort, an den Sie die Informationen senden, die Sie im Webhook erfassen.

Wenn Sie Informationen an einen Anbieter senden möchten, sollte der Anbieter diese URL in seiner API-Dokumentation bereitstellen. Wenn Sie Informationen an Ihre eigenen Systeme senden, wenden Sie sich an Ihr Entwicklerteam, um sicherzustellen, dass Sie die richtige URL verwenden.

Braze erlaubt nur URLs, die über die Standardports 80 (HTTP) und 443 (HTTPS) kommunizieren.

Liquid verwenden

Sie können Ihre Webhook-URLs mithilfe von Liquid personalisieren. Manchmal erfordern bestimmte Endpunkte, dass Sie Nutzer:innen identifizieren oder nutzerspezifische Informationen als Teil Ihrer URL bereitstellen. Wenn Sie Liquid verwenden, stellen Sie sicher, dass Sie für jede nutzerspezifische Information, die Sie in Ihrer URL verwenden, einen Standardwert angeben.

HTTP-Methode

Die HTTP-Methode, die Sie verwenden sollten, variiert je nach Endpunkt, an den Sie Informationen senden. In den meisten Fällen verwenden Sie POST.

Anfrage-Body

Der Anfrage-Body enthält die Informationen, die an die von Ihnen angegebene URL gesendet werden. Sie können den Body Ihrer Webhook-Anfrage mit JSON-Schlüssel-Wert-Paaren oder Rohtext erstellen.

JSON-Schlüssel-Wert-Paare

JSON-Schlüssel-Wert-Paare ermöglichen es Ihnen, einfach eine Anfrage für einen Endpunkt zu schreiben, der ein JSON-Format erwartet. Sie können dies nur mit einem Endpunkt verwenden, der eine JSON-Anfrage erwartet. Wenn Ihr Schlüssel beispielsweise message_body ist, könnte der entsprechende Wert Your order just arrived! sein. Nachdem Sie Ihr Schlüssel-Wert-Paar eingegeben haben, konfiguriert der Composer Ihre Anfrage in JSON-Syntax und eine Vorschau Ihrer JSON-Anfrage wird automatisch angezeigt.

Sie können Ihre Schlüssel-Wert-Paare mithilfe von Liquid personalisieren, z. B. indem Sie beliebige Nutzerattribute, angepasste Attribute oder Event-Eigenschaften in Ihre Anfrage einbinden. Beispielsweise können Sie den Vornamen und die E-Mail-Adresse von Kund:innen in Ihre Anfrage aufnehmen. Stellen Sie sicher, dass Sie für jedes Attribut einen Standardwert angeben.

Rohtext

Die Rohtext-Option bietet Ihnen die Flexibilität, eine Anfrage für einen Endpunkt zu schreiben, der einen Body in beliebigem Format erwartet. Beispielsweise können Sie dies verwenden, um eine Anfrage für einen Endpunkt zu schreiben, der Ihre Anfrage im XML-Format erwartet.

Sowohl Personalisierung als auch Übersetzungs-Tags werden in Rohtext unterstützt.

Wenn Sie den Content-Type-Anfrage-Header auf application/x-www-form-url-encoded setzen, muss der Anfrage-Body als URL-codierter String formatiert sein. Zum Beispiel:

1

to={{custom_attribute.${example}}}&text=Your+order+just+arrived

Schritt 3: Zusätzliche Einstellungen konfigurieren

Anfrage-Header (optional)

Bestimmte Endpunkte erfordern möglicherweise, dass Sie Header in Ihre Anfrage einschließen. Im Abschnitt Compose des Composers können Sie so viele Header hinzufügen, wie benötigt werden.

Gängige Anfrage-Header sind Content-Type-Spezifikationen (die beschreiben, welche Art von Daten im Body erwartet werden, z. B. XML oder JSON) und Authorization-Header, die Ihre Zugangsdaten für Ihren Anbieter oder Ihr System enthalten.

Hinweis

HTTP-Header-Namen sind gemäß RFC 7230, Abschnitt 3.2 („Each header field consists of a case-insensitive field name“) nicht case-sensitiv. Wenn Ihr empfangender Endpunkt oder zwischengeschaltete Dienste (wie CDNs) die Groß-/Kleinschreibung von Headern ändern, hat dies keinen Einfluss auf die Header-Verarbeitung – Content-Type, content-type und CONTENT-TYPE werden alle identisch behandelt.

Content-Typ-Spezifikationen müssen den Schlüssel Content-Type verwenden. Gängige Werte sind application/json oder application/x-www-form-urlencoded.

Authorization-Header müssen den Schlüssel Authorization verwenden. Gängige Werte sind Bearer {{YOUR_TOKEN}} oder Basic {{YOUR_TOKEN}} , wobei YOUR_TOKEN die von Ihrem Anbieter oder System bereitgestellten Zugangsdaten sind.

Schritt 4: Testnachricht senden

Bevor Sie Ihre Campaign live schalten, empfiehlt Braze, den Webhook zu testen, um sicherzustellen, dass die Anfrage korrekt formatiert ist.

Wechseln Sie dazu zum Tab Test und senden Sie einen Test-Webhook. Sie können den Webhook als zufällige:r Nutzer:in, als bestimmte:r Nutzer:in (durch Eingabe der E-Mail-Adresse oder externen Nutzer-ID) oder als angepasste:r Nutzer:in mit Attributen Ihrer Wahl testen.

Nach dem Senden des Test-Webhooks erscheint ein Dialog mit der Antwortnachricht. Wenn die Webhook-Anfrage nicht erfolgreich ist, nutzen Sie die Fehlermeldung zur Fehlerbehebung Ihres Webhooks. Das folgende Beispiel zeigt die Antwort eines Webhooks mit einer ungültigen Webhook-URL.

1
2
3
4
5
6
7
8
9

404 Not Found

{
  "error": {
    "message": "Unrecognized request URL. Please see https://lob.com/docs or email us at [email protected].",
    "status_code": 404
  }
}

Weitere Informationen finden Sie unter Testnachrichten senden.

Schritt 5: Erstellen Sie den Rest Ihrer Campaign oder Ihres Canvas

• campaign
• canvas

Erstellen Sie als Nächstes den Rest Ihrer Campaign. In den folgenden Abschnitten finden Sie weitere Details zur optimalen Nutzung unserer Tools für die Erstellung von Webhooks.

Wählen Sie einen Zustellzeitplan oder Trigger

Webhooks können basierend auf einem geplanten Zeitpunkt, einer Aktion oder einem API-Trigger zugestellt werden. Weitere Informationen finden Sie unter Ihre Campaign planen.

Bei aktionsbasierter Zustellung können Sie auch die Dauer der Campaign und die Ruhezeiten festlegen.

In diesem Schritt können Sie auch Zustellungskontrollen festlegen, z. B. ob Nutzer:innen erneut berechtigt werden können, die Campaign zu erhalten, oder ob Frequency-Capping-Regeln aktiviert werden sollen.

Wählen Sie die Zielgruppe aus

Als Nächstes müssen Sie Nutzer:innen ansprechen, indem Sie Segments oder Filter auswählen, um Ihre Zielgruppe einzugrenzen. In diesem Schritt wählen Sie die größere Zielgruppe aus Ihren Segments aus und grenzen dieses Segment bei Bedarf mit unseren Filtern weiter ein. Sie erhalten automatisch eine Vorschau der ungefähren Segment-Population. Beachten Sie, dass die genaue Segment-Zugehörigkeit immer vor dem Versand der Nachricht berechnet wird.

Wichtig

Ihre Nachricht wird ausschließlich an Nutzer:innen gesendet, die bereits die Bedingungen erfüllen, die Sie im Schritt „Zielgruppe“ festgelegt haben. Anschließend müssen sie noch den Trigger erfüllen, den Sie im Schritt „Zustellung planen“ definieren. Stellen Sie sich die Zielgruppe als einen Warteraum vor – nur Personen, die sich bereits darin befinden, können voranschreiten, wenn die nächste Aktion erfolgt.

Wählen Sie Konversions-Events

Braze ermöglicht es Ihnen zu verfolgen, wie oft Nutzer:innen bestimmte Aktionen, sogenannte Konversions-Events, nach dem Empfang einer Campaign durchführen. Sie haben die Möglichkeit, ein Zeitfenster von bis zu 30 Tagen festzulegen, in dem eine Konversion gezählt wird, wenn die Nutzer:innen die angegebene Aktion ausführen.

Wenn Sie es noch nicht getan haben, vervollständigen Sie die verbleibenden Abschnitte Ihres Canvas-Schritts. Einzelheiten zum Aufbau des restlichen Canvas, einschließlich multivariater Tests und Mit BrazeAI^TM optimieren, finden Sie unter Canvas erstellen.

Schritt 6: Überprüfen und bereitstellen

Nachdem Sie den letzten Teil Ihrer Campaign oder Ihres Canvas fertiggestellt haben, überprüfen Sie die Details, testen Sie alles und senden Sie es ab!

Wissenswertes

Fehler, Wiederholungslogik und Timeouts

Webhooks basieren darauf, dass Braze-Server Anfragen an einen externen Endpunkt senden. Dabei können gelegentlich Fehler auftreten. Die häufigsten Fehler sind Syntaxfehler, abgelaufene API-Schlüssel, Rate-Limits und unerwartete serverseitige Probleme. Bevor Sie eine Webhook-Campaign senden:

• Testen Sie Ihren Webhook auf Syntaxfehler
• Stellen Sie sicher, dass personalisierte Variablen Standardwerte haben

Wenn Ihr Webhook nicht gesendet werden kann, wird eine Fehlermeldung im Nachrichtenaktivitätsprotokoll protokolliert, die Details wie den Fehlerzeitstempel, den App-Namen und Informationen zum Fehler enthält.

Wenn die Fehlermeldung nicht ausreichend Aufschluss über die Fehlerursache gibt, sollten Sie die Dokumentation des von Ihnen verwendeten API-Endpunkts prüfen. Diese enthält in der Regel eine Erklärung der Fehlercodes, die der Endpunkt verwendet, sowie deren übliche Ursachen.

Antwortcodes und Wiederholungslogik

Wenn die Webhook-Anfrage gesendet wird, gibt der empfangende Server einen Antwortcode zurück, der angibt, was mit der Anfrage passiert ist. Die folgende Tabelle fasst die verschiedenen Antworten zusammen, die der Server senden kann, wie sie sich auf die Campaign-Analytics auswirken und ob Braze im Fehlerfall versucht, die Campaign erneut zuzustellen:

Hinweis

Braze wiederholt die in diesem Abschnitt genannten wiederholbaren Statuscodes bis zu fünf Mal insgesamt (die ursprüngliche Anfrage plus vier Wiederholungen) mit zunehmender Verzögerung zwischen den Versuchen. Wenn Braze Ihren Endpunkt nicht erreichen kann, können Wiederholungen bis zu 24 Stunden fortgesetzt werden.

Jede Webhook-Anfrage hat ein Timeout von 120 Sekunden.

Retry-After- und Rate-Limit-Antwort-Header können beeinflussen, wie lange Braze vor einem wiederholbaren Versuch wartet (zum Beispiel nach 408, 429 oder 5XX). Sie machen nicht wiederholbare Antworten wie 401 nicht für eine Wiederholung berechtigt.

Hinweis

Wenn Webhook-Sendungen in den Analytics zu fehlen scheinen, öffnen Sie das Nachrichtenaktivitätsprotokoll für die Campaign oder den Canvas-Schritt. Braze wiederholt nur bestimmte Antworten (zum Beispiel 408, 429 und 5XX) – die meisten anderen 4XX-Client-Fehler, einschließlich 401 Unauthorized, werden nicht wiederholt. Die vollständige Antworttabelle finden Sie unter Antwortcodes und Wiederholungslogik.

403 Forbidden und IP-Allowlisting {#403-forbidden-and-ip-allowlisting}

403 Forbidden-Antworten bedeuten, dass Ihr Endpunkt die Anfrage empfangen, aber abgelehnt hat. Häufige Ursachen sind ungültige oder fehlende Authentifizierung, unzureichende API-Berechtigungen und Netzwerkregeln (wie eine Firewall oder Web Application Firewall), die die ausgehenden IP-Adressen von Braze blockieren.

Wenn Webhook-Anfragen regelmäßig 403 zurückgeben und Ihre Authentifizierungs-Header korrekt sind, setzen Sie die Braze-IPs für Ihren Cluster auf dem Server, der den Webhook empfängt, auf die Allowlist. Siehe IP-Allowlisting. Connected-Content-Anfragen verwenden dieselben ausgehenden IPs; siehe IP-Allowlisting für Connected Content.

Für weitere 4XX-Fehlerbehebungsschritte lesen Sie Fehlerbehebung bei Webhook- und Connected-Content-Anfragen.

Authentifizierung und Connected-Content-Zugangsdaten

Die ausgehende Webhook-HTTP-Anfrage unterstützt nicht das Anhängen von Connected-Content-Zugangsdaten (:basic_auth oder :auth_credentials) zur Authentifizierung gegenüber Ihrem Endpunkt. Konfigurieren Sie die Authentifizierung stattdessen über Anfrage-Header im Webhook. Um ein Token oder ein Secret zum Sendezeitpunkt abzurufen, können Sie ein {% connected_content %}-Tag in ein Header- oder Body-Feld einfügen, damit Liquid es auflöst, bevor der Webhook gesendet wird.

Gespeicherte Webhook-Templates und Campaign-Nutzung

Braze bietet keinen integrierten Bericht, der jede Campaign oder jeden Canvas-Schritt auflistet, die auf ein bestimmtes gespeichertes Webhook-Template verweisen. Um die Nutzung zu prüfen, überprüfen Sie Webhook-Schritte, die dieselbe URL und HTTP-Methode verwenden, oder wenden Sie sich an den Braze-Support.

Fehlerbehebung und zusätzliche Fehlerdetails

Ausführliche Erklärungen, Fehlerbehebungsschritte und Anleitungen zur Behebung spezifischer Webhook-Fehler finden Sie unter Fehlerbehebung bei Webhook- und Connected-Content-Anfragen. Dort finden Sie auch weitere Erklärungen zur Funktionsweise unseres Systems zur Erkennung ungesunder Hosts und dazu, wie Braze Fehlerbenachrichtigungen über automatisierte E-Mails und zusätzliche Protokollierung in Braze-Currents bereitstellt.

IP-Allowlisting

Wenn ein Webhook von Braze gesendet wird, stellen die Braze-Server Netzwerkanfragen an unsere Kund:innen oder Drittanbieterserver. Mit IP-Allowlisting können Sie überprüfen, ob Webhook-Anfragen von Braze stammen, und so eine zusätzliche Sicherheitsebene hinzufügen.

Braze sendet Webhooks von den folgenden IPs. Die aufgeführten IPs werden automatisch und dynamisch allen API-Schlüsseln hinzugefügt, die für das Allowlisting aktiviert wurden.

Wichtig

Wenn Sie einen Braze-zu-Braze-Webhook erstellen und Allowlisting verwenden, sollten Sie alle folgenden IPs auf die Allowlist setzen, einschließlich 127.0.0.1.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

Nutzer:innen löschen

Um einzelne Nutzer:innen oder ein Segment von Nutzer:innen zu löschen, gehen Sie zu Audience > Manage Audience > Delete Users. Das Dashboard unterstützt die Massenlöschung von Segmenten (bis zu 10 Millionen Profile), bietet ein 7-tägiges Stornierungsfenster und verbraucht keine gemeinsam genutzten REST-API-Rate-Limits. Für Schritte, Limits und Berechtigungen siehe Nutzer:innen löschen.

Für die programmatische Löschung in kleineren Chargen verwenden Sie den /users/delete-Endpunkt anstelle einer Webhook-Campaign.