Survey Webhook

The Survey Webhook feature allows your server to automatically execute an action when a user completes a survey. Common use cases include awarding in-app rewards, updating a completed status, populating a database, or automating other custom actions.

While Survey Webhooks support customizable JSON payloads for better compatibility with your existing services, some post-processing on your server may still be required. If you don’t have server access, we recommend using Zapier for third-party integrations. For Enterprise Plan and Business Plan users, please contact your account representative for assistance.

Survey Webhooks are available on the Essentials Plan and above.

How to Set Up a Webhook

Step 1 - Navigate to Integrations and select "Webhooks".
Step 2 - Go to the "My Webhooks" tab.
Step 3 - Click "+ Webhook"
Step 4 - Enter a name for your webhook.
Step 5 - Input your server's webhook URL.
Step 6 - Add any necessary headers, including authorization keys.
Step 7 - Select the survey(s) that will trigger this webhook. By default, it will apply to all surveys. If you want to restrict it to specific surveys, choose them during this step.

Webhook Request Details

The webhook sends a POST request to your provided URL, containing data from the survey completion event.

POST your_provided_callback_url

Webhook Payload

The webhook payload includes valuable data such as:

Survey details
User answers
External user ID (which you can pass as customer_id on the survey url or iframe url)

You can customize the JSON payload format from within the webhook editor. Preview the payload to ensure it matches the expected structure for third-party services.

The default JSON payload looks like this:


$data = [
    'survey_uuid' => int, // Survey UUID - eg.: 1ecf9a3e-6c69-4c63-b254-0f32a88e7f61
    'survey_name' => string, // Survey Name - eg.: My coll survey
    'user_session_id' => int, // Unique user Session ID - eg.: 123
    'user_external_id' => string, // Your provided customer_id for the user, or an auto-generated one if none was provided - eg.: bc7239d8844e90cc0ae56ce02570eea5 (or you id format)
    'answers' => [
        [
            'question_id' => int, // Question unique internal ID - eg.: 123
            'question_hash' => string, // Question hash - unique within the survey - eg.: 6AcjaBedTE
            'question_type' => string, //  Question type - eg.: radio, checkbox, text, rating, ...
            'question_title' => string, // Question title - eg.: What's your favorite color?
            'answer' => string | string[], // User answer(s), if is a single response (eg. radio), will be an string, if multiple (eg. checkbox) will a a string array. - eg.: ['Blue', 'Red']
        ]
        ...
    ],
    'started_at' => string, // Moment the user started the survey - eg.: 2024-01-01T14:52:02Z
    'completed_at' => string, // Moment the user completed the survey - eg.: 2024-01-01T14:52:02Z

    // The below keys will only be available if a value is provided on the survey settings

    // Only if reward data was provided in the settings
    'reward' => [
        'name' => string, // Reward name - eg.: Coins
        'amount' => string, // Reward amount - eg.: '500'
    ],

    // Only if a complete extra json was provided in the settings
    // NOTE: the json it's returned as a string, remember to parse it on your side
    'complete_extra_json' => string, // Your custom JSON provided in the settings, eg.: '{"param": 123}'
];