Overview
Webhooks provide a way to be notified, to a specified URL, when various events occur within FlexiQuiz. Depending on the event the notification will also include details within the message.
For example you can set the response.submitted event to call your url whenever one of your quizzes is submitted, the notification will include event details and results for the submitted quiz.
All webhook calls will include a payload in json format. The payload includes an event id, event type, delivery attempt, event date and data relating to the specific event that occurred.
Your url should respond with a 200 response code to indicate the message has been successfully received.
For more details on initially setting up webhooks for your account please review our API overview.
Example payload
{
"event_id": "59d80f60-56eb-47d3-b953-8880d8219d1c",
"event_type": "response.submitted",
"delivery_attempt": 1,
"event_date": "2018-11-02 00:05:47",
"data": {
"response_id": "1ac1c221-7a30-4f58-aad0-793ce22c4c73",
"quiz_id": "fcb5f59c-2a2f-44a9-8261-33cbfa97be99",
"quiz_name": "Economics",
"first_name": "Henry",
"last_name": "Patterson",
"email_address": "henry@flexiquiz.com",
"user_id": "cee9808d-b234-4a8d-8526-8fea6c335056",
"user_name": "henry@flexiquiz.com",
"date_submitted": "2018-11-02 00:05:47",
"points": 44,
"available_points": 88.00,
"percentage_score": 50,
"grade": "B",
"pass": true,
"duration": 452,
"attempt": 1,
"ip_address": "::1",
"status": "submitted",
"publish_type": "quiz_link",
"certificate_url": "",
"response_report_url": "not_in_use",
"registration_fields": []
}
}
Shared secrets
When configuring a webhook you can optionally include your own shared secret, this adds an extra layer of security and allows you to ensure that the call has come from FlexiQuiz.
When a webhook posts a message to your specified url the header will include a timestamp and signature. To verify the signature you append the timestamp string to the start of your shared secret, with a space between them, and then calculate the SHA256 HMAC of the full string.
POST {your_url}
In this example the shared secret is abab*
Example webhook headers
POST {your_url} content-type: application/json x_flexiquiz_timestamp: 2018-11-02 00:11:01 x_flexiquiz_signature: 44e5251bfb21e822bedb3ac22b1d69082110ef307a618135090f4c8de0137252 Signature calculation
x_flexiquiz_signature = HMAC-SHA256("2018-11-02 00:11:01 abab*")
Retry attempts
If your URL fails to respond with a 200 response code then the webhook message will be queued and retried up to 6 times.
| Retry attempt | Time from previous attempt | Time from original attempt |
| 1. | 5 minutes | 5 minutes |
| 2. | 55 minutes | 1 hour |
| 3. | 2 hours | 3 hours |
| 4. | 5 hours | 8 hours |
| 5. | 16 hours | 24 hours |
| 6. | 24 hours | 48 hours |
Dates
All dates are posted using the UTC timezone and in the format yyyy-MM-dd hh:mm:ss
Example Date
2018-10-21 08:06:59response.submitted
Occurs whenever a quiz within your account is submitted.
Example payload
{
"event_id": "daa28284-9f64-4a7b-bd74-ec6884fc6982",
"event_type": "response.submitted",
"delivery_attempt": 1,
"event_date": "2018-11-02 00:10:57",
"data": {
"response_id": "073763e7-b67f-487d-a4d4-19478525d942",
"quiz_id": "fcb5f59c-2a2f-44a9-8261-33cbfa97be99",
"quiz_name": "Economics",
"first_name": "Jane",
"last_name": "Jones",
"email_address": "jane@flexiquiz.com",
"user_id": null,
"user_name": null,
"date_submitted": "2018-11-02 00:10:56",
"points": 84,
"available_points": 88.00,
"percentage_score": 95,
"grade": "A",
"pass": true,
"duration": 400,
"attempt": 1,
"ip_address": "::1",
"status": "submitted",
"publish_type": "quiz_link",
"certificate_url": "",
"response_report_url": "not_in_use",
"registration_fields": [
{
"name": "First name",
"value": "Jane"
},
{
"name": "Last name",
"value": "Jones"
},
{
"name": "Email address",
"value": "jane@flexiquiz.com"
}
]
}
}
response.deleted
Occurs whenever a response within your account is deleted.
Example payload
{
"event_id": "24e6adf6-48f3-4ef1-835d-eaa935d5208e",
"event_type": "response.deleted",
"delivery_attempt": 1,
"event_date": "2018-11-02 08:29:24",
"data": {
"response_id": "7619468b-0f4d-4283-80e0-03944d5e2284",
}
}
user.created
Occurs whenever a user is created within your account.
Example payload
{
"event_id": "c1364321-001d-4a09-8cff-a6fc6012c90c",
"event_type": "user.created",
"delivery_attempt": 1,
"event_date": "2018-11-02 08:41:01",
"data": {
"user_id": "b49f019a-ebfb-4dd3-9969-adb8985f4c47",
"user_name": "hannah@flexiquiz.com",
"user_type": "respondent",
"email_address": "hannah@flexiquiz.com",
"first_name": "Hannah",
"last_name": "Rodgers",
"time_zone": "Mountain Standard Time",
"suspended": false,
"manage_users": false,
"manage_groups": false,
"edit_quizzes": false,
"quizzes": [
{
"quiz_id": "fcb5f59c-2a2f-44a9-8261-33cbfa97be99",
"name": "Economics",
"date_assigned": "2018-11-02 08:41:01"
},
{
"quiz_id": "6e73d1db-bb93-4107-992e-49da53bf8bc2",
"name": "Aptitude test",
"date_assigned": "2018-11-02 08:41:01"
}
],
"groups": [],
"trainerquizzes": [],
"trainergroups": [],
"date_created": "2018-11-02 08:41:01"
}
}
user.updated
Occurs whenever a user is created within your account.
The payload contains all user data and not just the updated fields.
Example payload
{
"event_id": "631c1fa9-94e0-438f-9990-ee7cb9db9b8e",
"event_type": "user.updated",
"delivery_attempt": 1,
"event_date": "2018-11-02 09:09:00",
"data": {
"user_id": "b49f019a-ebfb-4dd3-9969-adb8985f4c47",
"user_name": "hannah@flexiquiz.com",
"user_type": "trainer",
"email_address": "hannah@flexiquiz.com",
"first_name": "Hannah",
"last_name": "Rodgers",
"time_zone": "Mountain Standard Time",
"suspended": false,
"manage_users": true,
"manage_groups": true,
"edit_quizzes": true,
"quizzes": [
{
"quiz_id": "fcb5f59c-2a2f-44a9-8261-33cbfa97be99",
"name": "Economics",
"date_assigned": "2018-11-02 08:41:01"
},
{
"quiz_id": "6e73d1db-bb93-4107-992e-49da53bf8bc2",
"name": "Aptitude test",
"date_assigned": "2018-11-02 08:41:01"
}
],
"groups": [],
"trainerquizzes": [],
"trainergroups": [],
"date_created": "2018-11-02 08:41:01"
}
}
user.deleted
Occurs whenever a user is deleted within your account.
Example payload
{
"event_id": "4b4d7f62-5672-4f5b-8739-c5a109cc0583",
"event_type": "user.deleted",
"delivery_attempt": 1,
"event_date": "2018-11-02 09:22:24",
"data": {
"user_id": "5c1dbaad-68ee-4a58-aad6-349d541fd592",
}
}