Webhooks einrichten

Mit Webhooks überträgt bluebarry Daten aus deinem Produktquiz in Echtzeit an deine weiteren Tools.

Das Prinzip ist einfach: Jemand schließt einen Teil des Quiz ab, und dein E-Mail-Tool, CRM oder Automatisierungs-Workflow reagiert sofort darauf.

Anwendungsfälle für Webhooks

Typische Einsatzbereiche in Teams:

1. E-Mail-Strecken bei Abbrüchen auf der Ergebnisseite oder nach dem Produktquiz versenden
2. Quiz-Antworten und Profileigenschaften mit deinem ESP oder CRM synchronisieren
3. Workflows basierend auf konkreten Antwortentscheidungen auslösen
4. Ergebnisse personalisierter Produktempfehlungen in BI- oder Analytics-Tools speichern

Verfügbare Webhook-Topics

In bluebarry kannst du aus vier Webhook-Triggern wählen:

• question.answered: Wird jedes Mal gesendet, wenn jemand eine Frage beantwortet. Du kannst alle Produktquizze, ein einzelnes Quiz, eine Frage oder sogar eine ganz bestimmte Antwort tracken.
• result.viewed: Wird gesendet, sobald jemand die Ergebnisseite erreicht. Du kannst dies für alle Produktquizze oder ein bestimmtes Quiz aktivieren.
• profile.updated: Wird gesendet, wenn bluebarry ein Besucherprofil basierend auf dem Verhalten im Quiz aktualisiert. Du kannst dies für alle Produktquizze oder ein bestimmtes Quiz aktivieren.
• email.submitted: Wird gesendet, sobald jemand eine E-Mail-Adresse als Antwort eingibt. Du kannst dies für alle Produktquizze oder ein bestimmtes Quiz aktivieren.

Ein Profil in bluebarry ist der Besucherdatensatz, der aus Interaktionen im Produktquiz aufgebaut wird (zum Beispiel E-Mail-Adresse, antwortbasierte Eigenschaften, Consent und personalisierte Produktempfehlungen).

So funktionieren Topics (in bluebarry und der API)

Diese Topic-Formate entsprechen exakt der Struktur, die bluebarry in der App nutzt. Wenn du Webhook-Abonnements über die API anlegst, verwende genau diese Topic-Werte:

• question.answered
• question.answered.{quizId}
• question.answered.{quizId}.{questionId}
• question.answered.{quizId}.{questionId}.{answerId}
• result.viewed
• result.viewed.{quizId}
• profile.updated
• profile.updated.{quizId}
• email.submitted
• email.submitted.{quizId}

Ersetze die Platzhalter durch echte IDs. Aus result.viewed.{quizId}wird beispielsweise result.viewed.6f7f3ad1-0b8e-4e89-bd8f-2c625b3c9a11. Entferne die geschweiften Klammern und trage den tatsächlichen Wert ein.

So findest du deine quizIdin bluebarry: Öffne den Quiz-Funnel und wechsle zur Seite "Design". Die URL lautet /quizzes/{quizId}/design. Der mittlere Teil ist deine Quiz-ID.

Datenstruktur verstehen

Der Webhook nutzt deine internen Bezeichnungen aus bluebarry. Das garantiert Konsistenz, erfordert jedoch eine saubere Konfiguration:

• Interne Fragennamen: Ändere diese im linken Menü deines Funnels, in dem sich sämtliche Frageeinstellungen befinden
• Interne Antwortwerte: Aktualisiere diese im Bereich "Flow" (Ablauf) deines Quiz-Builders

Payload-Übersicht

Jeder Webhook überträgt einen JSON-Payload. Die konkreten Felder richten sich nach dem gewählten Trigger. Klicke in bluebarry auf "Example payload" (Beispiel-Payload), um eine Vorschau der Daten zu sehen, die dein System empfängt. Du findest diese Option unter "Integrations" → "Developer area" → "Webhooks" (Integrationen → Entwicklerbereich → Webhooks): beim Erstellen eines Webhooks (nach Auswahl eines Topic-Typs) sowie auf jeder gespeicherten Webhook-Karte.

• question.answered: Besucher- und Session-IDs, Details zur ausgewählten Antwort, Antwortwert/-text und Consent-Signal.
• result.viewed: Besucher- und Session-IDs, E-Mail-Adresse (falls vorhanden), beantwortete Fragen und empfohlene Produkte.
• profile.updated: Besucher- und Session-IDs, Profildetails (wie E-Mail-Adresse und Eigenschaften), Consent-Informationen und Empfehlungen.
• email.submitted: Besucher- und Session-IDs, übermittelte E-Mail-Adresse, Ursprungsfrage und Consent-Signal.

Bei Webhooks für Ergebnisse und Profile kann bluebarry auch Produktattribute wie Preis, Kategorie und weitere zugewiesene Produktdaten übertragen.

Historischer Sync für result.viewed-Daten

Um ältere Quiz-Ergebnisdaten per Backfill nachzuladen, nutze den OData-Endpunkt der Data API unter /data/AdvisorResultViewedSyncRecords. Er gibt einen Eintrag pro historischem Ergebnisaufruf zurück, inklusive Besucher-IDs, E-Mail-Adresse (falls erfasst), nach Fragen gruppierten Antworten und empfohlenen Produkten.

Typische Sync-Abfragen:

• GET /data/AdvisorResultViewedSyncRecords?$top=500&$skip=0&$orderby=createdDate asc,id asc
• GET /data/AdvisorResultViewedSyncRecords?$top=500&$skip=500&$orderby=createdDate asc,id asc
• GET /data/AdvisorResultViewedSyncRecords?$top=500&$skip=0&$filter=advisorId eq {quizId}&$orderby=createdDate asc,id asc

Übergib den Schlüssel der Data API als vollständigen Wert des Authorization-Headers, zum BeispielAuthorization: {apiKey}. Der Parameter $top ist erforderlich und beträgt maximal 5000. Erhöhe $skip schrittweise um die Seitengröße, bis die Antwort keine weiteren Datensätze mehr liefert. Empfehlungen behalten den Produktnamen, die URL und die ID des ursprünglichen Ergebnis-Events bei. Existiert das Produkt nicht mehr in bluebarry, wird die Empfehlung weiterhin mit productMissing: true zurückgegeben.

Zustellung und Wiederholungsversuche

• bluebarry sendet Webhook-Daten unmittelbar nach Auslösen des Triggers an deine URL.
• Eine Zustellung wird als erfolgreich markiert, sobald dein Empfangsendpunkt die Annahme bestätigt.
• Jeder Versuch wird in bluebarry unter dem jeweiligen Webhook mit Status und Zeitstempel protokolliert.
• Fehlgeschlagene Zustellungen kannst du unter "Delivery Attempts" (Zustellversuche) manuell wiederholen.
• Nach 5 aufeinanderfolgenden Fehlversuchen deaktiviert bluebarry den Webhook automatisch zum Schutz des Systems.

Webhook einrichten

1. Gehe zu "Integrations" → "Developer area" → "Webhooks" (Integrationen → Entwicklerbereich → Webhooks).
2. Klicke auf "Create webhook" (Webhook erstellen).
3. Gib einen Namen ein und wähle einen Topic-Typ aus.
4. Grenze den Webhook optional auf ein bestimmtes Quiz, eine Frage oder eine Antwort ein (abhängig vom Topic-Typ).
5. Füge die Ziel-URL deines Tools ein (zum Beispiel von Make, Zapier, einer Klaviyo-Middleware oder deinem CRM-Endpunkt).
6. Speichere den Webhook, starte ein kurzes Test-Quiz und überprüfe, ob die Daten korrekt ankommen.

Benutzerdefinierte Header

Du kannst jedem Webhook eigene HTTP-Header zuweisen. Diese Header werden bei jeder Zustellung mitgesendet und dienen der Authentifizierung oder dem Routing auf Empfängerseite.

Häufige Beispiele:

• Authorization: Bearer your-secret-token: Eingehende Anfragen authentifizieren, damit dein Endpunkt verifizieren kann, dass sie von bluebarry stammen.
• X-Source: bluebarry: Anfragen für das Routing oder Filtern in deiner Middleware kennzeichnen.

Um Header hinzuzufügen, klicke beim Erstellen oder Bearbeiten eines Webhooks auf "Add header" (Header hinzufügen). Trage jeweils Header-Name und Wert ein. Du kannst Header jederzeit im Bearbeitungsfenster des Webhooks hinzufügen, anpassen oder entfernen.

Testen und Fehlerbehebung

Nutze ein Tool wie webhook.site , um eingehende Daten vorab zu prüfen, bevor du deine Live-Automatisierung verknüpfst.

• Nutze "Example payload" (Beispiel-Payload) in bluebarry, um Felder vor dem Aufbau deines Workflows zuzuordnen.
• Prüfe die "Delivery Attempts" (Zustellversuche), um zu sehen, ob die Übertragungen erfolgreich waren oder fehlgeschlagen sind.
• Wird ein Webhook nach wiederholten Fehlern deaktiviert, behebe das Problem am empfangenden Endpunkt und schalte ihn wieder ein.