Webhooks

The Coremetrix system can notify your backend when certain events occur, using webhooks. You can subscribe to real-time events via the Coremetrix webhooks. The webhooks can be managed via the Subscriptions API.

This API can be used to subscribe to various events from the quiz lifecycle.

How it works:

Supported events

Currently we support subscriptions to the following events:

Note: The complete list of events you can subscribe to can be found by calling the/subscriptions/events endpoint:

Webhook payload

When creating a subscription via the Subscriptions API, you are required to provide an URL. When any of the events described above happen, Coremetrix will POST the corresponding data to the URL provided. Your API should be able to consume the following payload:

{
"event": "quiz_consent",
"consentTime": "2020-01-31T13:14:35.208Z",
"lastUpdated": "2020-01-31T13:14:35.208Z",
"slug": "sandbox",
"puid": "a_puid",
"quizId": "481ac0fe-ac33-402a-9367-2aaa7a98b49d",
"consent": true
}

{
"event": "quiz_consent_withdrawal",
"withdrawalTime": "2020-01-31T13:25:02.786Z",
"lastUpdated": "2020-01-31T13:25:02.786Z",
"slug": "sandbox",
"puid": "a_puid",
"quizId": "481ac0fe-ac33-402a-9367-2aaa7a98b49d",
"consent": false
}

Attempt status can be one of the following:

{
"event": "attempt_profiled",
"attemptId": "4d1c90d4-f1fe-4303-ad83-535d99a61cf5",
"quizId": "481ac0fe-ac33-402a-9367-2aaa7a98b49d",
"puid": "a_puid",
"age": "age",
"gender": "gender",
"maritalStatus": "maritalStatus",
"occupation": "occupation",
"accommodation": "accommodation",
"education": "education",
"profiles": {
"basic_profile": {
"value": "HIGH",
"scale": [
"LOW",
"MEDIUM",
"HIGH"
]
}
},
"profileFlags": { },
"status": "COMPLETED_SCORED"
}

Attempt status can be one of the following:

Security

Data encryption during transmission

Coremetrix employs encryption for all data transmission. The Subscriptions API will only accept the https protocol. This is to protect the communication between the Coremetrix system and your back end. You will need to turn on TLS on your server and configure the subscription URL to use https.

Basic http authentication

Coremetrix supports Basic http authentication in order to allow your backend to secure the subscriber URL. This will ensure that Coremetrix only will be able to post data to your server.

The Subscriptions API will allow you to create a subscriber URL with the following format: https://username:password@my_server.com/my_secure_path

Note: username and password should not contain any : or @ symbols.

OAuth 2.0

OAuth 2.0 is an open standard for authorization on the internet. Coremetrix supports OAuth 2.0 authorisation in order to allow our backend limited access to your webhook endpoint.

OAuth 2.0 requires an authentication token, which is issued by an authorization server.

In order to grant Coremetrix access to post data to your webhook endpoint, you must first setup your subscriptions using Subscriptions API.

For each subscription you must also provide the following configuration:

Note: These parameters will be added using the application/x-www-form-urlencoded format with a character encoding of UTF-8 in the HTTP request entity-body.

Full details can be found here.

How it works:

Client Credentials Flow

OAuth 2.0 specifies multiple flows for obtaining and validating tokens. Coremetrix supports the Client Credential Flow, where the communication is strictly server-to-server. No Refresh Token is issued in this flow since the client can retrieve a new Access Token using its credentials anyway.

When an event occurs, if OAuth 2.0 is configured:

1. To obtain an Access Token, Coremetrix will call your OAuth server passing the credential (previously registered via the Subscription API) The access token will be used when pushing data to the webhook.

JSON Web Tokens

JSON Web Tokens allow you to verify that the data sent to your server has not been tampered with and that it is actually coming from Coremetrix.

How it works:

1. Coremetrix will include the entire event data in the payload of the JWT token.
2. To prevent replay attacks, , Coremetrix will include a nonce (jti claim), the creation time (iat claim) and and an expiration time (exp claim) as part of the JWT payload. The expiration time is currently set to 60 seconds.
3. Coremetrix signs the JWT token using HS512 and your secret API key in the format “{apiKey}+{apiKey}”.
4. Coremetrix will send this token in a header called X-Coremetrix-Signature when posting data to your server.

Validating the JWT:

You will have to validate the JWT to verify its authenticity. You can do this by checking its digital signature and it's claims. There are various libraries out there to help you in doing this. For instance, you can use the jjwt library for java.

Retries and exponential backoff

Coremetrix will retry sending the events in case of error. In addition to the retries, Coremetrix implements exponential backoff algorithm to achieve better flow control. In case of error returned by your server when attempting to deliver the events, the Coremetrix system will retry after a period of time. The wait time will incrementally increase between consecutive retry requests after each failure. This will give your service enough time to recover

Coremetrix will retry sending messages to your system for up to 1 hour approximately. If your service is down for more than one hour, we recommend you use the Coremetrix report API to get the missing information.