How to Use involve.me Webhooks

Automatically Send JSON Structured Data to Your Endpoint and Code Your Own Integration

Adrian avatar
Written by Adrian
Updated over a week ago

Available on

❌ Free

❌ Basic

❌ Pro

✅ Business

involve.me 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 involve.me tailored to your business needs.

To use webhooks all you need to do is to add your endpoint URL to the integration settings. You'll find the "Webhooks" integration card after clicking on the "Integrations" menu option on the top navigation bar.

Start webhook configuration

After clicking "Connect", add your URL endpoint (eg. https://www.your-website.com/your-webhook) to the configuration popup.
Be aware that your website must accept secure connections (SSL over HTTPS only).

Webhook configuration popup

Before you click "Connect", you have the possibility to test if your endpoint is available and works. By clicking "Test Webhook" involve.me will send your newest participant to the endpoint currently specified in the input field (this also works for HTTP).

Testing the webhook connection

List of Available Webhooks

► Participant finished webhook (finished_participant)

This webhook is triggered when your project has a new submission, 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 involve.me 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" (decimal represented as string) - the score the participant got (sum of all answer values) or null if there are no questions with values

  • calculator_result: eg. "19.99" (decimal represented as string) - the result of the first calculator element or null if there is no calculator in the project

  • calculator_results: eg. {"d79imhx": 112.20, "f7fj306": 86.30} (json) - a json object that contains all calculator results with calculator ID and value.

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

  • outcome_points": eg. "19.99" (decimal represented as string) - the sum of all answer values assigned to the winning outcome or null if there are no questions with values

  • 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

  • embed_url: eg. "https://mywebsite.com" (string) - the URL of the website in case the project was completed on an embed or null if the data was not collected via an embed

  • device_type: (string) phone/tablet/computer

  • remote_id: (string) if defined or null if not present

  • 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 Form" 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 Single/Multiple Choice, Image Choice and Dropdown elements, "input" for Short/Long Answer elements, "slider" for Slider elements, "rating" for Rating elements, "checkbox" for Checkbox elements, "fileUpload" for File Upload elements and "dateTimePicker" for Date & Time 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" (decimal represented as string) - 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".

ℹ️ Hidden fields are treated as text answers, so you can find hidden field data in the question object.

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". If the type is "dateTimePicker" you can expect either date+time, only date or only time for this field in this format "YYYY-MM-DD hh:mm:ss".

  • response_image: eg. "https://assets.involve.me/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" (decimal represented as string) - 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" (decimal represented as string) - the input of the slider element. This property is only available if the question type is "slider".

  • slider_min: eg. "0.0" (decimal represented as string) - the minimum of the slider element range. This property is only available if the question type is "slider".

  • slider_max: eg. "10.5" (decimal represented as string) - the maximum of the slider element range. This property is only available if the question type is "slider".

  • file_url: (string) the URL to download the file uploaded through a File Upload element. This property is only available if the question type is "fileUpload".

  • file_name: eg. "photo.jpg" (string) - The original file name of an uploaded file. This property is only available if the question type is "fileUpload".

  • file_bytes: eg. 115471 (integer) - The storage size of the uploaded file in bytes.  This property is only available if the question type is "fileUpload".

  • file_type: eg. "image/jpeg" (string) - The MIME type of the uploaded file. This property is only available if the question type is "fileUpload".

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

If you have configured a webhook endpoint for a project and you duplicate the project, your webhook settings will duplicate as well.

Did this answer your question?