web-hook

cluetec header

cluetec logo

Documentation

mQuest HTTP webhook

Author: Christian Herrmann, cluetec GmbH, Germany
Version: 2.0
Date: 2022-08-01

Introduction and detailed documentation about the mQuest HTTP webhook.

Inhalt

History1.0 Introduction1.1 About events1.2 About notifications1.3 About links (mQuest API)1.4 Configuration1.5 Authentication1.6 Error handling1.7 Compatibility2.0 Documentation2.1 result2.2 result-with-media2.3 media2.4 task (documentation update coming soon)2.5 questionnaire (documentation update coming soon)2.6 ride (documentation update coming soon)2.7 group (documentation update coming soon)2.8 user (documentation update coming soon)

History

Version	Date	Description
0.1	2021-07-20	First draft by Christian Herrmann
1.0	2022-01-01	Peer reviewed by Kristian Ferkic
2.0	2022-08-01	Major update to the JSON payloads: result, media & result-with-media Added section 1.7 Compatibility

1.0 Introduction

mQuest webhook is part of an inter-system communication between three components. One being the customer's system (providing an http-endpoint), the mQuest API (and the mQuest webhook).

webhook

The mQuest webhook delivers lightweight notifications proactively to the customer's system. Notifications contain information (meta data) about events on the mQuest platform. Notifications are sent to an http-endpoint of the customer's system and deliver a JSON payload. After receiving a notification the customer's system can use the mQuest API to process the information for its individual use-case.

1.1 About events

On the mQuest platform there are a lot of events, that can be interesting, useful or even crucial for an external system (of a customer). E.g.

A project has been updated
A task has been deleted
A new data set is available (i.e. has been transferred from a mobile device)

The entire list of available events that can trigger notifications can be found on the following pages.

1.2 About notifications

Notifications contain very little data in order to remain lightweight. Their purpose is to inform the customer's system.

The JSON payload for an event indicating a new data set is available looks like this: Text behind the double-slash serves as explanation and is not part of the payload


xxxxxxxxxx
{
  // Your tenant number on the mQuest platform
  "tenant": "123001",
  
  // Indicates the notification is about a new data set (UPDATE or DELETE are also possible operations on any resource) 
  "operation": "CREATE", 
  
  // Indicates a data-set and all the corresponding media-file (e.g. photos) are available, i.e. have been transferred from the mobile device. There are also dedicated events for only the data-set and each media-file.
  "resource": "result-with-media",
  
  // The exact time the event occurred.
  "timestamp": "2020-09-07T17:35:00Z",
  
  // The _links (individual for every resource) lead to the mQuest API. 
  // More on links below in 1.3.
  "_links": {
    "self": {
      "href":"https://host.com/qs/123001/api/v4/projects/Customer-Survey/results/999"
    },
    "results": {
      "href":"https://host.com/qs/123001/api/v4/projects/Customer-Survey/results"
    },
    "project": {
      "href":"https://host.com/qs/123001/api/v2/projects/Customer-Survey"
    },
    "task": {
      "href":"https://host.com/qs/123001/api/v2/tasks/4711"
    }
  },
  
  // As for every resource, there are attributes that are specific to the resource. The following attributes are specific to the result(-with-media) resource.
  
  // Meta information about the corresponding task
  "task_id": 4711,
  "task_namespace": "company-api",
  "task_specifier": "571cd19b-d40a-4e6f-a36e-270fdfbd9475",
  "task_version": 1,
  "task_status": "IN_PROGRESS",

   // The name of the corresponding project (questionnaire) the data set belongs to.
  "questionnaire": "Customer-Survey",
  // The version of the corresponding project (questionnaire) the data set belongs to.
  "questionnaire_version": 42,
  
  // The ID of the user conducting/synchronizing the data set
  "user_id": "1264e9b8-e97f-4c28-92aa-703d12e853b7",
  
  // The (unique) ID of the data-set
  "id": "bWVkaWEtdGFnc3wyMTY0Ng==",
  // The legacy (numeric) ID of the data-set
  "result_id": 999, 
  
  // Indicates if the data-set has been ignored (probably only relevant for the UPDATE operation)
  "ignored": false,
  // Indicates the data set has been canceled (if true)
  "canceled": false,
  // Status information of the result
  "status": "COMPLETED",
  
  // Meta information about the data-set ONLY available with result-store persistence
  "stats": {
    "total_response_count": 99,
    "hidden_response_count": 2
  },
  
  // Meta version of the webhook itself
  "__version__": 2
}

1.3 About links (mQuest API)

Most of the times, receiving a notification is only the first step in the process. E.g. after being informed about a new data-set (result-with-media), you probably want to load the actual data-set (and all its media-files).

You do this using the the mQuest API: https://api.mquest.de/

Now the_links attribute in the payload already contains the most commonly used endpoints for the corresponding resource and serves as a suggestion on how to proceed. However, depending on you use-case and process, feel free to use any endpoints that serves you.

1.4 Configuration

It is important to know, that you are free to choose, about which events you want to be notified. Not only can you "subscribe" to notifications about certain resources, you can also combine the configuration with the operation that is relevant for you.

Available combinations are:

resource	CREATE	UPDATE	DELETE
result	x	x	x
result-with-media	x
media	x
task	x	x	x
questionnaire	x	x	x
ride	x
group	x	x	x
user	x	x	x

1.5 Authentication

This is about supported authentication on the endpoint that is exposed in the customer's system. The configuration of the webhook is capable of applying any http-header. I.e. we can send BasicAuth or an API-key with the notification requests. Certificate based authentication (mutual TLS) is not supported yet.

1.6 Error handling

If a notification for any event couldn't be sent to the endpoint of the customer's system (e.g. there has been a connection timeout or the http-response-code was not in the allowed 2xx-range), mQuest webhook will retry after 15 minutes. Failing attempts will be retried 1500 times, every 15 minutes (which is aprox. 15 days). If the event couldn't be delivered after 1500 retries, the event will be discarded.

1.7 Compatibility

Additional attributes in the payload are not considered a breaking change. I.e. when serializing the JSON payload, use a configuration that ignores unknown attributes. Existing attributes will neither be changed nor removed.

2.0 Documentation

On the following pages, you'll find example payloads for every resource including a detailed description for each attribute.

2.1 result

This event is about the data set and only the data set, i.e. if the data set contains media file (e.g. photos) - for the CREATE operation - you will receive a notification even before all the corresponding media-files are available. Regardless of media-files you will receive notifications, once the result has been updated (UPDATE operation) or deleted (DELETE operation). The event for a DELETE operation will only be published once a single data set has been deleted. If the project has been deleted, which implies deleting all data set. There will be only an event for questionnaire.


xxxxxxxxxx
{
  // The attribtes "tenant", "operation", "resource" and "timestamp" are available for all resources. The description can be found in the example above in chapter 1.2.
  "tenant": "123001",
  "operation": "CREATE",
  "resource": "result",
  "timestamp": "2020-09-07T17:35:00Z",
  
  // These attributes are the same for the resource "result" and "result-with-media". The description can be found in the example above in chapter 1.2.
  "task_id": 4711,
  "task_namespace": "company-api",
  "task_specifier": "571cd19b-d40a-4e6f-a36e-270fdfbd9475",
  "task_version": 1,
  "task_status": "IN_PROGRESS",
  "questionnaire": "Customer-Survey",
  "questionnaire_version": 42,
  "user_id": "1264e9b8-e97f-4c28-92aa-703d12e853b7",
  
  "ignored": false,
  "canceled": false,
  "status": "COMPLETED",
  
  "stats": {
    "total_response_count": 99,
    "hidden_response_count": 2
  },
  
  // The (unique) ID of the data-set
  "id": "bWVkaWEtdGFnc3wyMTY0Ng==",
  // The legacy (numeric) ID of the data-set
  "result_id": 999, 
  
  // Detailed description about the mQuest API is available at https://api.mquest.de
  "_links": {
    "self": {
      "href":"https://host.com/qs/123001/api/v2/projects/Customer-Survey/results/999"
    },
    "results": {
      "href":"https://host.com/qs/123001/api/v2/projects/Customer-Survey/results"
    },
    "project": {
      "href":"https://host.com/qs/123001/api/v2/projects/Customer-Survey"
    },
    "task": {
      "href":"https://host.com/qs/123001/api/v2/tasks/4711"
    }
  },
  
  "__version__": 2 // Meta version of the webhook itself
}

2.2 result-with-media

This event is about the data set and all the media-files (e.g. photos) that belong to the data set. This event occurs only once the data set and all the media-files are available, i.e. have been successfully transferred from the mobile device. I.e. this event occurs only in combination with the CREATE operation.


xxxxxxxxxx
{
  // The attribtes "tenant", "operation", "resource" and "timestamp" are available for all resources. The description can be found in the example above in chapter 1.2.
  "tenant": "123001",
  "operation": "CREATE",
  "resource": "result-with-media",
  "timestamp": "2020-09-07T17:35:00Z",
  
  // These attributes are the same for the resource "result" and "result-with-media". The description can be found in the example above in chapter 1.2.
  "task_id": 4711,
  "task_namespace": "company-api",
  "task_specifier": "571cd19b-d40a-4e6f-a36e-270fdfbd9475",
  "task_version": 1,
  "task_status": "IN_PROGRESS",
  "questionnaire": "Customer-Survey",
  "questionnaire_version": 42,
  "user_id": "1264e9b8-e97f-4c28-92aa-703d12e853b7",
  
  "ignored": false,
  "canceled": false,
  "status": "COMPLETED",
  
  "stats": {
    "total_response_count": 99,
    "hidden_response_count": 2
  },
  
  // The (unique) ID of the data-set
  "id": "bWVkaWEtdGFnc3wyMTY0Ng==",
  // The legacy (numeric) ID of the data-set
  "result_id": 999, 
  
  // Detailed description about the mQuest API is available at https://api.mquest.de
  "_links": {
    "self": {
      "href":"https://host.com/qs/123001/api/v2/projects/Customer-Survey/results/999"
    },
    "results": {
      "href":"https://host.com/qs/123001/api/v2/projects/Customer-Survey/results"
    },
    "project": {
      "href":"https://host.com/qs/123001/api/v2/projects/Customer-Survey"
    },
    "task": {
      "href": "https://host.com/qs/123001/api/v2/tasks/4711"
    }
  },
  
  "__version__": 2 // Meta version of the webhook itself
}

2.3 media

This event is about a single media file. This resource only supports the CREATE operation, once the file has been successfully transfered from the mobile device.


xxxxxxxxxx
{
  // The attribtes "tenant", "operation", "resource" and "timestamp" are available for all resources. The description can be found in the example above in chapter 1.2.
  "tenant": "123001",
  "operation": "CREATE",
  "resource": "media",
  "timestamp": "2020-09-10T15:33:00Z",
  
  // Meta information about the corresponding task
  "task_id": 4711,
  "task_version": 1,
  "task_status": "IN_PROGRESS",
  
   // The name of the corresponding project (questionnaire) the data set belongs to.
  "questionnaire": "Customer-Survey",
  // The version of the corresponding project (questionnaire) the data set belongs to.
  "questionnaire_version": 42,
  // The ID of the user conducting/synchronizing the data set
  "user_name": "1264e9b8-e97f-4c28-92aa-703d12e853b7",
  
  // ID of the corresponding data set
  "result_id": 999,
  // File name of the media file
  "file_name": "Customer-Survey-FOTO-999+1.jpg",
  
  // Detailed description about the mQuest API is available at https://api.mquest.de
  "_links": {
    "self": {
      "href": "https://host.com/qs/123001/api/v2/projects/Customer-Survey/results/999/medias/Customer-Survey-FOTO-999+1.jpg"
    },
    "raw": {
      "href": "https://host.com/qs/123001/api/v2/projects/Customer-Survey/results/999/medias/Customer-Survey-FOTO-999+1.jpg/raw"
    },
    "medias": {
      "href": "https://host.com/qs/123001/api/v2/projects/Customer-Survey/results/999/medias"
    },
    "result": {
      "href": "https://host.com/qs/123001/api/v2/projects/Customer-Survey/results/999"
    },
    "project": {
      "href": "https://host.com/qs/123001/api/v2/projects/Customer-Survey"
    }
  }
}

2.4 task (documentation update coming soon)

This event is about the task. Task are context "around" the questionnaire (project). Typically all operations are releveant, i.e. CREATE, UPDATE and DELETE.


xxxxxxxxxx
{
  // The attribtes "tenant", "operation", "resource" and "timestamp" are available for all resources. The description can be found in the example above in chapter 1.2.
  "tenant": "123001",
  "operation": "UPDATE",
  "resource": "task",
  "timestamp": "2020-12-24T12:34:00Z",
  
  // The ID of the task
  "id": 4711,
  // The current version of the task
  "version": 56,
  // Task attribute: namespace is part of the task's unique identifier
  "namespace": "demo",
  // Task attribute: specifier is part of the task's unique identifier
  "specifier": "ca455f59-5b44-462e-b88a-52e9345bb6a9",
  // The corresponding project / questionnaire that belongs to the task
  "project": "Customer-Survey",
  // The current status of the task
  "status": "IN_PROGRESS",
  // The task's name (displayed e.g. in the mobile App or SurveyManager)
  "name": "Demo Customer Survey",
  
  // Detailed description about the mQuest API is available at https://api.mquest.de
  "_links": {
    "self": {
      "href": "https://host.com/qs/123001/api/v2/tasks/4711"
    },
    "tasks": {
      "href": "https://host.com/qs/123001/api/v2/tasks"
    },
    "project": {
      "href": "https://host.com/qs/123001/api/v2/projects/Customer-Survey"
    }
  }
}

2.5 questionnaire (documentation update coming soon)

This event is about the questionnaire (form) of the project (sometimes refered to as the project itself). Typically all operations are releveant, i.e. CREATE, UPDATE and DELETE.


xxxxxxxxxx
{
  // The attribtes "tenant", "operation", "resource" and "timestamp" are available for all resources. The description can be found in the example above in chapter 1.2.
  "tenant": "123001",
  "operation": "CREATE",
  "resource": "questionnaire",
  "timestamp": "2021-04-01T12:34:56Z",
  
  // ID, name, version and UUID of the questionnaire
  "id": 1234,
  "name": "Customer-Survey",
  "version": 56,
  "uuid": "8f9253af-ba16-43c7-9c24-1395e7f9e4a0",
  
  // Detailed description about the mQuest API is available at https://api.mquest.de
  "_links": {
    "self": {
      "href": "https://host.com/qs/123001/api/v2/projects/Customer-Survey"
    },
    "projects": {
      "href": "https://host.com/qs/123001/api/v2/projects"
    }
  }
}

2.6 ride (documentation update coming soon)

This event is about a single ride. A ride is a special kind of data set, conducted by the mQuest traffic app, for traffic projects. It contains multiple counts. After the mobile app has successfully transferred, a ride event will be published using the CREATE operation.


xxxxxxxxxx
{
  // The attribtes "tenant", "operation", "resource" and "timestamp" are available for all resources. The description can be found in the example above in chapter 1.2.
  "tenant": "123001",
  "operation": "CREATE",
  "resource": "ride",
  "timestamp": "2021-01-01T10:01:00Z",
  
  // ID of the ride
  "id": 1338,
  // Internal ID of the ride
  "ride_id": 1,
  // Unique ID (text) of the ride
  "unique_ride_id": "9b80dbb1-b870-4cd7-a867-7ca11aed1b81",
  // The ride's name
  "ride_name": "Ride 101",
  // Name of the corresponding project / questionnaire
  "project": "Traffic-Survey",
  // Version of the corresponding project / questionnaire
  "project_version": 73,
  // Timestamp of the rides synchronization (once it has been received by the mobile app)
  "handover": "2021-01-01T10:00:59Z",
  
  // Detailed description about the mQuest API is available at https://api.mquest.de
  "_links": {
    "self": {
      "href": "https://host.com/qs/123001/api/v2/projects/Traffic-Survey/rides/1338"
    },
    "rides": {
      "href": "https://host.com/qs/123001/api/v2/projects/Traffic-Survey/rides/"
    },
    "counts": {
      "href": "https://host.com/qs/123001/api/v2/projects/Traffic-Survey/rides/1338/counts"
    },
    "project": {
      "href": "https://host.com/qs/123001/api/v2/projects/Traffic-Survey"
    }
  }
}

2.7 group (documentation update coming soon)

This event is about a single group. User can be organized in groups. Typically all operations are releveant, i.e. CREATE, UPDATE and DELETE.


xxxxxxxxxx
{
  // The attribtes "tenant", "operation", "resource" and "timestamp" are available for all resources. The description can be found in the example above in chapter 1.2.
  "tenant": "123001",
  "operation": "CREATE",
  "resource": "group",
  "timestamp": "2020-31-12T23:59:00Z",
  
  // ID of the group
  "id": "719352d8-3de1-4ddb-99e9-9f053d854619",
  // Name of the group
  "name": "Team A",
  // Path of the group - relevant if it is a sub-group
  "path": "/department-C/team-A",
  
  // Detailed description about the mQuest API is available at https://api.mquest.de
  "_links": {
    "self": {
      "href": "https://host.com/qs/123001/api/v2/groups/719352d8-3de1-4ddb-99e9-9f053d854619"
    },
    "groups": {
      "href": "https://host.com/qs/123001/api/v2/groups"
    }
  }
}

2.8 user (documentation update coming soon)

This event is about a single user. Typically all operations are releveant, i.e. CREATE, UPDATE and DELETE.


xxxxxxxxxx
{
  // The attribtes "tenant", "operation", "resource" and "timestamp" are available for all resources. The description can be found in the example above in chapter 1.2.
  "tenant": "123001",
  "operation": "DELETE",
  "resource": "user",
  "timestamp": "2020-31-12T23:59:59Z",
  
  // ID of the user
  "id": "c480b6b8-bf27-41ea-ad02-8b539bf88bb2",
  // Indicates if the user is enabled, i.e. can authenticate himself on the system
  "enabled": true,
  // User name used for authentication 
  "user_name": "ee@cluetec.de",
  // First & last name and email of the user
  "first_name": "Eddi",
  "last_name": "Example",
  "email": "e.example@cluetec.de",
  
  "_links": {
    "self": {
      "href": "https://host.com/qs/123001/api/v2/users/c480b6b8-bf27-41ea-ad02-8b539bf88bb2"
    },
    "users": {
      "href": "https://host.com/qs/123001/api/v2/users"
    }
  }
}