Webhooks

Le système Coremetrix peut notifier votre backend lors de certains événements, en utilisant des webhooks. Vous pouvez vous abonner aux événements en temps réel via les webhooks Coremetrix. Les webhooks peuvent être gérés via l'API des abonnements.

Cette API peut être utilisée pour vous abonner à divers événements du cycle de vie du quiz.

Comment cela fonctionne :

Événements pris en charge

Actuellement, nous prenons en charge les abonnements aux événements suivants:

Remarque : La liste complète des événements auxquels vous pouvez vous abonner peut être trouvée en appelant l'endpoint/subscriptions/events endpoint:

Charge utile du webhook

Lors de la création d'un abonnement via l'API des abonnements, vous devez fournir une URL. Lorsque l'un des événements décrits ci-dessus se produit, Coremetrix POSTera les données correspondantes à l'URL fournie. Votre API doit être capable de consommer la charge utile suivante :

{
"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
}

Le statut de la tentative peut être l'un des suivants :

{
"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"
}

Le statut de la tentative peut être l'un des suivants :

Sécurité

Chiffrement des données lors de la transmission

Coremetrix utilise le chiffrement pour toutes les transmissions de données. L'API des abonnements n'acceptera que le protocole https. Cela est destiné à protéger la communication entre le système Coremetrix et votre backend. Vous devrez activer TLS sur votre serveur et configurer l'URL d'abonnement pour utiliser https.

Authentification http de base

Coremetrix prend en charge l'authentification http de base afin de permettre à votre backend de sécuriser l'URL du souscripteur. Cela garantira que seul Coremetrix pourra poster des données sur votre serveur.

L'API des abonnements vous permettra de créer une URL de souscripteur selon le format suivant : https://username:password@my_server.com/my_secure_path

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

OAuth 2.0

OAuth 2.0 est une norme ouverte pour l'autorisation sur Internet. Coremetrix prend en charge l'autorisation OAuth 2.0 afin de permettre à notre backend d'avoir un accès limité à votre point de terminaison webhook.

OAuth 2.0 nécessite un jeton d'authentification, qui est émis par un serveur d'autorisation.

Pour accorder à Coremetrix l'accès pour poster des données à votre point de terminaison webhook, vous devez d'abord configurer vos abonnements en utilisant l'API des abonnements.

Pour chaque abonnement, vous devez également fournir la configuration suivante :

Remarque : Ces paramètres seront ajoutés en utilisant le format application/x-www-form-urlencoded avec un encodage de caractères UTF-8 dans le corps de la requête HTTP.

Vous pouvez trouver tous les détails ici.

Comment cela fonctionne :

Flux de crédits client

OAuth 2.0 spécifie plusieurs flux pour obtenir et valider les jetons. Coremetrix prend en charge le flux des crédits client, où la communication est strictement de serveur à serveur. Aucun jeton de rafraîchissement n'est émis dans ce flux, car le client peut récupérer un nouveau jeton d'accès en utilisant ses informations d'identification de toute façon.

Lorsqu'un événement se produit, si OAuth 2.0 est configuré :

1. Pour obtenir un jeton d'accès, Coremetrix appellera votre serveur OAuth en passant les informations d'identification (préalablement enregistrées via l'API des abonnements). Le jeton d'accès sera utilisé lors de la transmission des données au webhook.

Jetons Web JSON

Jetons Web JSON vous permettent de vérifier que les données envoyées à votre serveur n'ont pas été altérées et qu'elles proviennent réellement de Coremetrix.

Comment cela fonctionne :

1. Coremetrix inclura toutes les données d'événement dans la charge utile du jeton JWT.
2. Pour éviter les attaques par rejeu, , Coremetrix inclura un nonce (jti réclamation), l'heure de création (iat réclamation) et une heure d'expiration (exp réclamation) dans la charge utile du JWT. L'heure d'expiration est actuellement définie à 60 secondes.
3. Coremetrix signe le jeton JWT en utilisant HS512 et votre clé API secrète sous le format “{apiKey}+{apiKey}”.
4. Coremetrix enverra ce jeton dans un en-tête appelé X-Coremetrix-Signature lors de l'envoi de données à votre serveur.

Validation du JWT :

Vous devrez valider le JWT pour vérifier son authenticité. Vous pouvez le faire en vérifiant sa signature numérique et ses revendications. Il existe diverses bibliothèques pour vous aider à le faire. Par exemple, vous pouvez utiliser la jjwt pour Java.

Nouvelles tentatives et atténuation exponentielle

Coremetrix retentera l'envoi des événements en cas d'erreur. En plus des nouvelles tentatives, Coremetrix met en œuvre l'algorithme d'atténuation exponentielle pour obtenir un meilleur contrôle du flux. En cas d'erreur renvoyée par votre serveur lors de la tentative de livraison des événements, le système Coremetrix retentera après un certain temps. Le temps d'attente augmentera de manière incrémentielle entre chaque demande de nouvelle tentative après chaque échec. Cela donnera à votre service suffisamment de temps pour récupérer

Cependant, dans certains scénarios, comme une interruption prolongée du côté de Coremetrix ou du côté de l'abonné, les événements peuvent ne pas être transmis via des webhooks via le mécanisme de nouvelle tentative. Pour résoudre ce problème, Coremetrix fournit un mécanisme de relecture d'événements qui vous permet de demander manuellement la relecture d'événements passés. Cela garantit qu'aucune donnée critique n'est perdue en raison de pannes temporaires. Vous trouverez plus d'informations sur l'utilisation de cette fonctionnalité dans le API de relecture.

Veuillez noter que pour protéger nos systèmes et garantir une utilisation équitable, ce point de terminaison de relecture est limité. Si trop de demandes de relecture sont effectuées sur une courte période, les demandes peuvent être retardées ou rejetées. Nous vous recommandons d'utiliser cette fonctionnalité judicieusement et d'implémenter votre propre logique de nouvelle tentative lorsque cela est possible.