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.
{
"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": []
}
}
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.
In this example the shared secret is abab*
POST {your_url} content-type: application/json x_flexiquiz_timestamp: 2018-11-02 00:11:01 x_flexiquiz_signature: 44e5251bfb21e822bedb3ac22b1d69082110ef307a618135090f4c8de0137252
x_flexiquiz_signature = HMAC-SHA256("2018-11-02 00:11:01 abab*")
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 |
All dates are posted using the UTC timezone and in the format yyyy-MM-dd hh:mm:ss
2018-10-21 08:06:59
Occurs whenever a quiz within your account is submitted.
{
"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"
}
]
}
}
Occurs whenever a response within your account is deleted.
{
"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",
}
}
Occurs whenever a user is created within your account.
{
"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"
}
}
Occurs whenever a user is created within your account.
The payload contains all user data and not just the updated fields.
{
"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"
}
}
Occurs whenever a user is deleted within your account.
{
"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",
}
}