Webhooks einrichten

Webhooks schicken Quizaktivität in dem Moment an ein anderes System, in dem sie passiert. Jemand beantwortet eine Frage oder hinterlässt seine E-Mail-Adresse, und dein CRM, E-Mail-Tool oder deine Automatisierung reagiert sofort.

Wofür Teams Webhooks nutzen

• E-Mail-Strecken nach einem Quiz in Tools starten, die bluebarry nicht direkt anbindet.
• Antworten und Profildaten mit einem CRM abgleichen.
• Abläufe bei einer ganz bestimmten Antwort auslösen.
• Empfehlungen in einem Data Warehouse oder BI-Tool speichern.

Webhook-Themen

Du kannst aus fünf Themen (Topics) wählen:

Webhook einrichten

1. Geh zu Integrations, öffne den Developer area und klick bei Webhooks auf Manage.
2. Klick auf Create webhook.
3. Gib einen Webhook name ein und wähl einen Topic type.
4. Grenz ihn je nach Thema optional mit Quiz funnel, Question und Answer ein.
5. Füg die Adresse, die die Daten empfangen soll, bei Callback URL ein.
6. Klick optional auf Add header, um eigene Header mitzuschicken (siehe unten).
7. Klick auf Create webhook und kopier das Signing Secret, das Studio anzeigt. Du siehst es nur einmal.
8. Teste mit deinem Live-Quiz und prüf, ob die Daten ankommen.

Fragen und Antworten gut benennen

Webhooks nutzen die internen Namen deiner Fragen und Antworten. Du siehst und änderst sie im Tab Test flow des Quiz. Mit „Q1“ und „A1“ kommst du beim Bauen einer Automatisierung nicht weit, mit sprechenden Namen wie „budget“ und „unter_500“ schon.

Was jeder Webhook enthält

• question.answered: Besucher- und Sitzungs-ID, die gewählte Antwort mit Wert und die Einwilligung.
• result.viewed: Besucher- und Sitzungs-ID, die E-Mail-Adresse, wenn bekannt, die beantworteten Fragen und die empfohlenen Produkte.
• profile.updated: Besucher- und Sitzungs-ID, Profildaten wie E-Mail und Eigenschaften, Einwilligung und Empfehlungen.
• email.submitted und phone.submitted: Besucher- und Sitzungs-ID, E-Mail-Adresse oder Telefonnummer, die Frage, aus der sie stammt, und die Einwilligung.

Ergebnis- und Profil-Webhooks können Produktdetails wie Preis und Kategorie enthalten. Klick beim Anlegen oder bei einem gespeicherten Webhook auf Example payload, um genau zu sehen, was du bekommst. Alle Felder im Detail stehen in der Webhook-Payload-Referenz.

Eigene Header

Header, die du hinzufügst, gehen bei jeder Zustellung mit. Damit prüft dein Endpunkt, dass eine Anfrage von dir kommt, zum Beispiel mit Authorization: Bearer dein-geheimer-token, oder leitet sie weiter, zum Beispiel mit X-Source: bluebarry. Ändern kannst du sie jederzeit im Bearbeiten-Dialog des Webhooks. Jede Zustellung trägt außerdem einen Header Idempotency-Key, damit dein Endpunkt Duplikate überspringen kann.

Signing Secret

bluebarry signiert jede Zustellung, damit dein Endpunkt prüfen kann, dass eine Anfrage wirklich von bluebarry kommt. Wenn du einen Webhook anlegst, zeigt Studio sein Signing Secret einmal an. Kopier es und speichere es bei deinem Endpunkt. Jede Anfrage trägt einen Header bluebarry-signature, der mit diesem Secret erstellt ist. Wie du ihn prüfst, steht in der Webhook-Payload-Referenz.

Secret verloren oder vielleicht nach außen gelangt? Öffne den Bearbeiten-Dialog des Webhooks und klick auf Rotate secret. Du bekommst ein neues Secret, und das alte funktioniert sofort nicht mehr.

Zustellung und Wiederholungen

• bluebarry sendet die Daten direkt nach dem Ereignis. Eine Zustellung gilt als erfolgreich, wenn dein Endpunkt sie annimmt.
• Jeder Versuch steht mit Status und Uhrzeit unter Delivery Attempts. Dort kannst du eine fehlgeschlagene Zustellung wiederholen.
• Nach 5 Fehlschlägen in Folge deaktiviert bluebarry den Webhook zur Sicherheit. Behebe das Problem beim Empfänger und klick dann auf das Abzeichen Disabled, um ihn wieder auf Active zu stellen.

Themenformate für die API

Legst du Webhooks über die API an, nutz diese Werte. Ersetz die Platzhalter ohne geschweifte Klammern durch echte IDs.

• 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}
• phone.submitted
• phone.submitted.{quizId}

Eine Quiz-ID findest du in der Adressleiste, wenn das Quiz geöffnet ist: /quiz-funnels/{quizId}/design.

Ältere Ergebnisse abrufen

Webhooks decken nur neue Aktivität ab. Für vergangene Ergebnisse, etwa beim Einrichten eines neuen CRM, nutzt du den Data-API-Endpunkt /data/AdvisorResultViewedSyncRecords. Er liefert einen Datensatz pro Ergebnisaufruf mit Besucher-IDs, der E-Mail-Adresse, wenn bekannt, den Antworten und den empfohlenen Produkten. Schick deinen API-Schlüssel als vollständigen Authorization-Header, setz $top (bis 5000) und blättere mit $skip, zum Beispiel:

GET /data/AdvisorResultViewedSyncRecords?$top=500&$skip=0&$orderby=createdDate asc,id asc

Mit $filter=advisorId eq {quizId} bekommst du ein einzelnes Quiz. Empfehlungen behalten Produktname, URL und ID vom Zeitpunkt des Ergebnisses und sind mit productMissing: true markiert, wenn es das Produkt nicht mehr gibt.

Tipps zum Testen

• Die Vorschau im Quiz-Editor sendet keine Webhooks. Teste mit deinem veröffentlichten Quiz im Shop.
• Ein Request-Inspector wie webhook.site zeigt eingehende Daten, bevor du deine echte Automatisierung anbindest.
• Prüf unter Delivery Attempts, ob jede Sendung geklappt hat.