Help / Webhooks Reference

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:59

response.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",
    }
}