Webhook Survey Response Data Push
Monitor survey response events for a specific survey. For surveys with Webhook push enabled, when specific events occur, HTTP requests will be sent using the POST method to one or more specified URLs, with JSON format data and an application/json content-type header.
Currently supported events:
| action | Description |
|---|---|
| answer.create | User submits a response |
| answer.update | User/admin modifies a response |
| answer.delete | Admin deletes a response |
If you need support for other event types, please contact us.
Configuration Steps
Enter the survey editing page, click "Settings" in the top left corner, find "Webhook" under "Collection Settings", and click "Configure" on the right to open the Webhook settings page;
Click "New Webhook" and fill in the configuration items as prompted. "URL" should be a publicly accessible HTTP/HTTPS service address. Additional optional key items for verification will be added later. (Target address cannot contain
xip.io,@, port numbers, or be an internal network address)Check [Enable Push], click [OK] button to complete the configuration. The survey server will then send a test request for verification purposes.
Data Format Dictionary
Response Data
General Format Description
{
"id": "33cc555f-056f-4242-a97c-46f3e7d2016f", // uuid
"object": "Answer", // object
"action": "answer.create", // event
"created_at": "2021-01-26 14:00:00", // push time
"payload": {
// Survey ID
"survey_id": 5356056,
// Response ID
"answer_id": 7,
// Respondent ID in survey system, not actual QQ number
"respondent_id": 60000000001,
// Respondent login type (WeChat/QQ/Enterprise WeChat/Mobile etc.)
"respondent_type": "",
// Custom field (Not WeChat OpenID, deprecated field)
"openid": "",
// Time user started the survey
"started_at": "2020-02-09 11:55:30",
// Time user submitted the survey
"ended_at": "2020-02-09 11:58:39",
// Response duration (seconds)
"duration": 189,
// Geographic location information
"country": "China", // Country or region
"province": "Guangdong", // Province
"city": "Shenzhen", // City
// Client information
"ip": "127.0.0.1", // Response IP address
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148", // Browser information
"referrer": "https://wesurvey.com/xxx.html", // Source address of survey page entry
// Third-party user information (Only used in third-party integration scenarios, refer to https://wesurvey.com/docs/openapi/sso/create_user)
"third_party_user": {
"respondent_id": 60000000001, // Respondent ID in survey system, automatically generated during user registration
"openid": "abcdefg", // Third-party user identifier, provided by user during registration
"nickname": "Zhang San" // Third-party user nickname, provided by user during registration
},
// User's response details
"answer": [
// Structure varies by survey, actual data structure will be as per actual push
]
}
}
| Parameter | Description |
|---|---|
| id | uuid |
| object | Object |
| action | Action |
| created_at | Push time |
| payload | Specific content |
| payload.survey_id | Survey ID |
| payload.answer_id | Response ID |
| payload.qq | User identifier in Wesurvey (not QQ number) |
| payload.openid | Not WeChat OpenID, deprecated field |
| payload.weixin_openid | User's WeChat OpenID in Wesurvey (default empty) |
| payload.weixin_tp_openid | User's WeChat OpenID in authorized official account (default empty) |
| payload.started_at | Time user started responding |
| payload.ended_at | Time user submitted response |
| payload.answer | User's response details (includes custom parameters) |
| payload.score | User's response score (only available for old evaluation questions, for new exam surveys use Get Exam Score API) |
| payload.third_party_user | Third-party user information (specific use, related to Third-party System Integration) |
| signature | Signature for verification (not currently provided) |
payload.answer Description
[
{
"id": "p-1-ib8x", // First page
"questions": [
{
"id": "q-1-IFMp", // Question ID
"type": "radio", // Question type - Single choice
"options": [
{
"id": "o-100-ABCD", // Answer ID
"checked": 1, // Selected
"text": "<p>Option</p>\n" // Answer content
}
]
},
{
"id": "q-2-EcPa",
"type": "select", // Question type - Dropdown
"options": [
{
"id": "o-101-EFGH",
"checked": 1,
"text": "Option"
}
]
},
{
"id": "q-3-9K6v",
"type": "checkbox", // Question type - Multiple choice
"options": [
{
"id": "o-100-ABCD",
"checked": 1,
"text": "<p>Option</p>\n"
}
]
},
{
"id": "q-4-Ksi9",
"type": "text", // Question type - Single line text
"text": "123"
},
{
"id": "q-5-k7p1",
"type": "textarea", // Question type - Multi-line text
"text": "123123\n123123"
},
{
"id": "q-6-pZzn",
"type": "star", // Question type - Rating scale
"text": "5"
},
{
"id": "q-7-JNkO",
"type": "matrix_radio", // Question type - Matrix single choice
"groups": [
{
"id": "g-1-ABCD",
"options": [
{
"id": "o-101-EFGH",
"checked": 1,
"text": "<p>Option</p>\n"
}
]
},
{
"id": "g-2-EFGH",
"options": [
{
"id": "o-101-EFGH",
"checked": 1,
"text": "<p>Option</p>\n"
}
]
}
]
},
{
"id": "q-8-a5nI",
"type": "matrix_checkbox", // Question type - Matrix multiple choice
"groups": [
{
"id": "g-1-ABCD",
"options": [
{
"id": "o-100-ABCD",
"checked": 1,
"text": "<p>Option</p>\n"
},
{
"id": "o-101-EFGH",
"checked": 1,
"text": "<p>Option</p>\n"
}
]
},
{
"id": "g-2-EFGH",
"options": [
{
"id": "o-100-ABCD",
"checked": 1,
"text": "<p>Option</p>\n"
},
{
"id": "o-101-EFGH",
"checked": 1,
"text": "<p>Option</p>\n"
}
]
}
]
}
]
},
{
"id": "p-2-ohuS",
"questions": [
{
"id": "q-9-VDhO",
"type": "matrix_star", // Question type - Matrix rating scale
"groups": [
{
"id": "g-1-ABCD",
"text": "5"
},
{
"id": "g-2-EFGH",
"text": "5"
}
]
},
{
"id": "q-10-SZMU",
"type": "sort", // Question type - Ranking
"options": [
{
"id": "o-101-EFGH",
"sort_no": 1
},
{
"id": "o-100-ABCD",
"sort_no": 2
}
]
},
{
"id": "q-11-vtGs",
"type": "chained_selects", // Question type - Cascading
"id_list": [
"2-AK",
"3-nV",
"4-qA"
],
"text_list": [
"1",
"2",
"3"
]
},
{
"id": "q-12-MBer",
"type": "upload", // Question type - Attachment
"expired": "7d", // Link valid for 7 days
"url": "", // Deprecated, now supports multiple attachments, please use files field
"files": [{
"name": "Image1.png",
"url": "https://xxx.png"
},{
"name": "Image2.png",
"url": "https://yyy.png"
}]
},
{
"id": "q-14-Xlvy",
"type": "text_multiple", // Question type - Fill in the blanks
"blanks": [
{
"id": "fillblank-WPph",
"value": "wesurvey.com"
}
]
},
// Epidemic declaration survey, get uploaded health code and image recognition results
{
"id": "q-10-Zr6w",
"type": "upload",
"expired": "7d", // Link valid for 7 days
"files": [{
"name": "Nucleic acid test.png",
"url": "https://zzz.png"
}],
}, {
"id": "q-9-fRX5-ret",
"type": "radio",
"options": [{
"id": "o-102-FEAS",
"text": "Abnormal", // Currently only returns [Normal/Abnormal]
"checked": 1
}]
}
]
},
{
"id": "custom_args", // Custom parameters
"questions": [
{
"id": "custom-arg-01", // Custom parameter ID
"type": "text", // Type
"text": "123", // Content
"title": "userid", // Custom parameter key value
"description": "User ID, passing user identity information" // Custom parameter description
}
]
}
]
Server-side Debugging Example
Here's an example using PHP:
<?php
// Accept request parameters
$event = json_decode(file_get_contents("php://input"));
// Write to file
$myfile = fopen("wesurvey.com.log", "w") or die("Unable to open file!");
fwrite($myfile, json_encode($event));
fclose($myfile);
Check if wesurvey.com.log contains the received test request data, for example:
{
"id": "ac3a878b-3ada-4f00-a052-fb60c33414de", // uuid
"object": "webhook", // object
"action": "webhook.test", // action
"created_at": "2021-01-26 14:49:39", // push time
}
Retry Mechanism
After successfully receiving Webhook content, the server should return HTTP status code 200 within 5 seconds, otherwise, it will be considered a push failure. Failed Webhook events will enter the retry queue with a maximum of 7 retries.
Retry rules:
- First retry: 2 minutes after initial failure
- Second retry: 10 minutes after initial failure
- Third retry: 30 minutes after initial failure
- Fourth retry: 1 hour after initial failure
- Fifth retry: 2 hours after initial failure
- Sixth retry: 6 hours after initial failure
- Seventh retry: 15 hours after initial failure
Security
Verifying if Webhook Requests are from Wesurvey
Webhook requests will be initiated from a set of IP addresses, which receivers can use to verify request authenticity. Please obtain the IP list through the IP List API.