Webhooks instellen

Webhooks sturen quizactiviteit naar een ander systeem op het moment dat het gebeurt. Iemand beantwoordt een vraag of laat zijn e-mailadres achter, en je CRM, e-mailtool of automatisering kan meteen reageren.

Waar teams webhooks voor gebruiken

• E-mailreeksen na een quiz of na een verlaten resultaat starten in een tool waar bluebarry geen standaardkoppeling mee heeft.
• Antwoorden en profielgegevens synchroniseren met een CRM.
• Workflows starten op één specifiek antwoord.
• Aanbevelingen opslaan in een datawarehouse of BI-tool.

Webhooktopics

Je kunt kiezen uit vijf topics:

Een webhook instellen

1. Ga naar Integrations, open de Developer area en klik op Manage naast Webhooks.
2. Klik op Create webhook.
3. Vul een Webhook name in en kies een Topic type.
4. Maak het eventueel specifieker met Quiz funnel, Question en Answer, afhankelijk van het topic.
5. Plak het adres dat de data moet ontvangen in Callback URL.
6. Klik eventueel op Add header om eigen headers mee te sturen (zie hieronder).
7. Sla op, doe een test met je live quiz en controleer of de data binnenkomt.

Geef je vragen en antwoorden goede namen

Webhooks gebruiken de interne namen van je vragen en antwoorden. Je ziet en wijzigt ze op het tabblad Test flowvan de quiz. Met "Q1" en "A1" heb je weinig als je een automatisering bouwt. Met beschrijvende namen als "budget" en "under_500" wel.

Wat elke webhook bevat

• question.answered: bezoekers- en sessie-ID, het gekozen antwoord en de waarde ervan, en de keuze voor toestemming.
• result.viewed: bezoekers- en sessie-ID, het e-mailadres als dat bekend is, de beantwoorde vragen en de aanbevolen producten.
• profile.updated: bezoekers- en sessie-ID, profielgegevens zoals e-mailadres en properties, toestemming en aanbevelingen.
• email.submitted en phone.submitted: bezoekers- en sessie-ID, het e-mailadres of telefoonnummer, de vraag waar het vandaan kwam en de keuze voor toestemming.

Webhooks voor resultaten en profielen kunnen productdetails bevatten, zoals prijs en categorie. Klik op Example payload tijdens het aanmaken van een webhook of bij een opgeslagen webhook om precies te zien wat je ontvangt. Alle velden staan uitgelegd in de naslag voor webhook-payloads.

Eigen headers

Headers die je toevoegt, gaan mee met elke levering. Gebruik ze zodat je endpoint kan controleren of een request van jou komt, bijvoorbeeld Authorization: Bearer your-secret-token, of om requests te routeren, bijvoorbeeld X-Source: bluebarry. Je kunt ze altijd wijzigen in het bewerkvenster van de webhook. bluebarry ondertekent leveringen niet, dus een geheime header is de manier om ze te verifiëren. Elke levering heeft ook een header Idempotency-Key, zodat je endpoint dubbele leveringen kan overslaan.

Levering en nieuwe pogingen

• bluebarry verstuurt de data direct na het event. Een levering telt als geslaagd als je endpoint die accepteert.
• Elke poging staat onder Delivery Attempts met status en tijd. Een mislukte levering kun je daar opnieuw proberen.
• Na 5 mislukte leveringen op rij zet bluebarry de webhook voor de zekerheid uit. Los het probleem aan de ontvangende kant op en klik dan op het label Disabled om hem weer op Active te zetten.

Topicformaten voor de API

Maak je webhooks aan via de API? Gebruik dan deze topicwaarden. Vervang de placeholders door echte ID's, zonder de accolades.

• 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}

Een quiz-ID vind je in de adresbalk als de quiz open staat: /quiz-funnels/{quizId}/design.

Oudere resultaten ophalen

Webhooks gaan alleen over nieuwe activiteit. Wil je eerdere resultaten laden, bijvoorbeeld als je een nieuw CRM inricht? Gebruik dan het Data API-endpoint /data/AdvisorResultViewedSyncRecords. Dat geeft per bekeken resultaat één record terug met bezoekers-ID's, het e-mailadres als dat bekend is, de antwoorden en de aanbevolen producten. Stuur je API-sleutel mee als volledige header Authorization, stel $top in (maximaal 5000) en blader met $skip, bijvoorbeeld:

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

Voeg $filter=advisorId eq {quizId} toe voor één quiz. Aanbevelingen bewaren de productnaam, URL en ID van het moment van het resultaat, en krijgen productMissing: true als het product niet meer bestaat.

Tips voor testen

• De preview in de quizeditor verstuurt geen webhooks. Test met je gepubliceerde quiz in je webshop.
• Een request-inspector zoals webhook.site laat binnenkomende data zien voordat je je echte automatisering koppelt.
• Kijk bij Delivery Attempts of elke verzending is gelukt.