Brandquiz can automatically send JSON structured data to an endpoint on your server. Using webhooks you can easily code your own integration or process the data you collected with brandquiz tailored to your business needs.

To use webhooks all you need to do is to add your endpoint URL to the integration settings. You can configure webhooks for your organization (all projects) or have a custom webhook on a project level. You'll find this setting on your integration page in the "webhooks tab". This feature is only available with a Pro plan or higher.

Add your URL endpoint (eg. https://www.your-website.com/your-webhook) and click "save webhook". Be aware that your website must accept secure connections (SSL over HTTPS only).

Before you save your endpoint you have the possibility to test if your endpoint is available and works. By clicking "Test connection" brandquiz will send your newest participant to the endpoint currently specified in the input field (this also works for HTTP). Depending if your are configuring the webhook for your organization or for a specific project, the test will send the overall newest participant or the newest participant for the specific project.

To disable or remove your webhook just delete the URL from the input field and save.

Currently, these webhooks are available:

► Participant finished webhook (finished_participant)

This webhook is triggered when your project has a new participant, meaning that your user reached the last page (thank you page or outcome page).

Event (object)

  • type: "finished_participant" (string) - the name of this webhook you should check against it to identify the event
  • version: 1 (integer) - the version of this webhook (currently always 1)
  • created_at: eg. "YYYY-MM-DD HH:MM:SS" (string) date and time in UTC when the webhook was triggered

Data (object)

  • participant_id: eg. "9c3e839e2aacc5bd8bff7deb2ad039eb" (string) - unique identifier for your brandquiz participant. You may want to save this for future identification. This might be null if the "test connection" function does not find a participant.
  • project_name: eg. "My Project" (string) - the name of the project your participant completed
  • project_url: eg. "my-project" (string) - the URL snippet of your project
  • correctly_answered: eg. 5 (integer) - the amount of correctly answered questions or null if there are no questions in the project
  • score: eg. 37.5 (float) - the score the participant got (sum of all answer values) or null if there are no questions with values
  • calculator_result: eg. 19.99 (float) - the result of the calculator element or null if there is no calculator in the project
  • has_outcomes: eg. true (boolean) - is true if the project has multiple outcomes and false if not. Use this property to detect the expected structure in further question data objects.
  • outcome: eg. "My Outcome #1" (string) - the name of the outcome for the participant - this property is only available if has_outcomes is true.
  • country_code: eg. "US" (string) - the country code that was detected based on the IP of the participant or null if no country could be detected
  • anonymized_ip: eg. "c234a39a7469be63dc31f044e520e43323b9688d" (string) - the anonymized and hashed IP address for the participant. You can use this to identify duplicate entries.
  • seconds_to_complete: eg. 35 (integer) - the time in seconds it took the participant from loading the project until getting to the last page
  • opened_at: eg. "YYYY-MM-DD HH:MM:SS" (string) - the timestamp (UTC) when the participant loaded the project
  • finished_at: eg. "YYYY-MM-DD HH:MM:SS" (string) - the timestamp (UTC) when the participant finished the project (got to the last page)
  • personal_data: (object) an object that contains all personal data collected with the "Contact Info" element. The properties are all strings or null if not collected. This object contains always the following properties: first_name, last_name, email, title, gender, birthday, organization_name, job_title, street_address, zip_code, city, state, country, phone, mobile, fax, website, social_facebook, social_twitter, social_instagram, social_linkedin
  • questions: (array) an array containing an object for every question in the project. This object is described right below.

The question object (inside the "questions" array):

  • id: eg. "8211e586e9b2fd29bc3707c619ca359d" (string) - a unique identifier that lets you identify the question. This ID will change if you cut & paste the question in the editor and it will also be new for a duplicated project.
  • type: (string) the type of the question - "default" for Multiple Choice, Image Answer and Dropdown elements, "input" for Free Text Input elements, "slider" for Slider elements, "rating" for Rating elements and "checkbox" for Checkbox elements. Use this property to detect the expected structure of this question object and its answer objects.
  • question_text: eg. "What do you like most?" (string) - the text of this question
  • answered_correctly: eg. true (boolean) - Specifies if this question was answered correctly. For "multiple answers selectable" this is only true if all correct answers and no incorrect answer was selected by the participant. This property is only available if has_outcomes is false and if the question type is "default".
  • max_value: eg. 8.8 (float) - the maximum value a participant can reach by answering this question. For multiple answers selectable this is the sum of all answer values, for single selectable answers this is the maximum of all existent answer values. This property is only available if type is "default".
  • checked: eg true (boolean) - Describes if a checkbox element was checked. Be aware that this property is only available if type is "checkbox".
  • answers_given: (array) an array containing an object for every answer the participant has given for this question (may be empty). This object is described below. Be aware that this property is only available if type is not "checkbox".

The answer object (inside the "answers_given" array):

  • response_text: eg. "I'm a new customer" (string) - the text of this answer. Be aware that this property is not available for question type "rating" and "slider".
  • response_image: eg. "https://app.brandquiz.io/image-path.png" (string) - the absolute path to the image of the answer. This property is only available if type is "default" and is null if the question is not an Image Answer element.
  • connected_outcome: eg. "My Outcome #1" (string) - The name of the outcome that was endorsed by this answer. This can be the same string as the outcome property if this outcome was the result. This property is only available if has_outcomes is true and if the question type is "default".
  • correct: eg. false (boolean) - Specifies if this answer is marked as correct in the Editor. Be aware that this does not mean that the whole question was answered correctly. Check the question object for this. This property is only available if has_outcomes is false and if the question type is "default".
  • value: eg. 3.5 (float) - The individual value specified for this answer. This property is only available if the question type is "default".
  • rating_percent: eg. 0.75 (float) - the percentage between 0-1 that was chosen for a rating element. This property is only available if the question type is "rating".
  • rating_input: eg. 4 (integer) - the input of a rating element (eg. 4 out of 5 stars). This property is only available if the question type is "rating".
  • rating_max: eg. 5 (integer) - the maximum of a rating element (eg. 5 stars). This property is only available if the question type is "rating".
  • slider_input: eg. 4.5 (float) - the input of the slider element. This property is only available if the question type is "slider".
  • slider_min: eg. 0.0 (float) - the minimum of the slider element range. This property is only available if the question type is "slider".
  • slider_max: eg. 10.5 (float) - the maximum of the slider element range. This property is only available if the question type is "slider".

We highly recommend to send a test entry to your endpoint to double check that the structure is as you expect it to be. You can use a webhook tester to check the structure of your project's participants.

Duplicated projects: Be aware that if you have configured a webhook endpoint on the project level and you duplicate the project, your webhook setting will duplicate as well.

Did this answer your question?