API d'évènements Webhook

Vue d'ensemble du Webhook

Les abonnements Webhook permettent à une application de s'abonner aux événements qui se produisent sur Dokeop. Ces événements sont poussés vers une URL de callback, spécifiée lors de l'abonnement, peu de temps après que les événements se produisent sur Dokeop. Les webhooks permettent aux plates-formes d'inscription de recevoir des mises à jour en temps réel pour certains évènements, éliminant ainsi le besoin d'interroger l'API Dokeop.

Données d'évènement

L'API d'événements Webhook de Dokeop se déclenche pour toute modification apportée aux inscriptions ou à l'accès aux données d'un utilisateur. Plus précisément, les événements Webhook sont poussés lorsqu'un utilisateur (athlète ou organisateur) révoque l'accès à l'application, ou lorsque le statut d'une inscription évolue.

Lorsqu'un de ces événements se produit sur Dokeop, une demande POST est adressée à l'URL de rappel pour chaque abonnement auquel l'événement se rapporte. Le corps de cette demande POST contient le type d'object object_type, le type d'aspect aspect_type de la modification, ainsi que l'identifieur unique de l'objet object_id, qui est soit un identifieur unique d'inscription, soit un identifieur unique d'utilisateur. Si des informations supplémentaires sur l'objet sont requises, l'application peut décider d'interroger l'API pour les obtenir. Par exemple il est possible d'obtenir le type de document lié à l'inscription suite à sa validation par Dokeop.

Le serveur servant l'URL de rappel de l'abonnement doit accuser réception du POST de chaque nouvel événement avec un code HTTP 200 OK dans les 2 secondes. Les tentatives d'événement sont retentées (jusqu'à trois tentatives) si 200 n'est pas renvoyé. Si votre la plateforme d'inscription doit traiter davantage les informations reçues, elle doit le faire de manière asynchrone.

Ci-dessous les champs inclus avec les événements webhook:

aspect_type string	Toujours "updated" or "deleted"
object_type string	Toujours "registration" ou "athlete" ou "organizer" ou "club" ou "doctor"
object_id long integer	Pour un évènement inscription, l'identifieur unique de l'inscription. Pour un évènement utilisateur, l'identifieur unique de l'utilisateur.
updates hash	Pour un évènement inscription, les clés contienne: "platform_id": l'identifieur unique de l'inscription sur la plateforme si renseigné "registration_status_code": le code du statut d'inscription `[:waiting_document, :waiting_new_document, :waiting_check, :validated, :refused, :cancelled, :creating_expected_attachments, :no_attachment_expected]` "registration_status": le libellé du statut d'inscription "document_type_code": le code du type de document `[:certificate, :licence, :health_questionnaire]` "document_type": le libellé du type de document "document_status_code": le code du statut du document `[:waiting_check, :validated, :refused]` "document_status": le libellé du statut du document "reasons": le(s) motif(s) si un document est refusé "comment": le commentaire éventuel si un document est refusé Pour un évènement de révocation d'accès aux données de l'utilisateur. il y a toujours la paire clé-valeur "authorized" : "false"
subscription_id integer	L'identifieur unique de l'abonnement qui reçoit cet évènement.
event_time long integer	L'heure à laquelle l'événement s'est produit.

Exemple d'évènement

{
  "aspect_type": "updated",
  "object_type": "registration",
  "object_id": 14624,
  "subscription_id": 11,
  "updates": {
    "platform_id": "123ABC",
    "registration_status_code": "waiting_new_document",
    "registration_status": "Attente nouveau document",
    "document_type_code": "certificate",
    "document_type": "Certificat médical",
    "document_status_code": "refused",
    "document_status": "Refusé",
    "reasons": [
      "Langue du document non acceptée",
      "Mention(s) de certificat médical erronée(s) ou non acceptée(s)",
      "Cachet et/ou signature absent(s)"
    ],
    "comment": "Commentaire \"personnalisés\" avec 'caractère spéciaux /"
  },
  "event_time": 1574432698
}

Conformément au Contrat de l'API Dokeop, les applications doivent respecter les choix en matière d'accès aux données des utilisateurs et supprimer le jeton d'accès de l'utilisateur lorsque ce dernier révoque l'accès à ses données et que l'évènement correspondant est reçu via le Webhook.

Abonnements

Chaque application ne peut avoir qu'un seul abonnement, mais cet abonnement unique lui permettra de recevoir des événements Webhook pour toutes les modifications relatives aux inscriptions ou lors des révocations d'accès à une application par un utilisateur.

Créer un abonnement

La création d'un nouvel abonnement webhook est un processus en deux étapes:

Demandez la création d'un abonnement en appelant POST https://dokeop.com/api/v1/webhook_subscription. Cette demande définit l'adresse de rappel callback_url où les événements seront envoyés, ainsi qu'un jeton de vérification verify_token utilisé lors de la validation de l'adresse de rappel.
Valider l'adresse de rappel. À la réception d’une demande de création d’abonnement, le système webhook de Dokeop envoie une demande GET à l’adresse de rappel nouvellement définie pour valider sa disponibilité. Pour que l'abonnement soit validé et activé, le serveur qui sert l'adresse de rappel doit répondre à cette requête GET de manière correcte et rapide.

À noter que seul un jeton d'accès (voir Authentification) correspondant à un utilisateur plateforme d'inscription sera autorisé à accéder au point d'accès /api/v1/webhook_subscription

Requête de création d'abonnement

Ci-dessous les paramètres requis pour créer un abonnement aux événements webhook. Les paramètres doivent être inclus dans une clé webhook_subscription

callback_url required string, in body	Adresse de rappel où les évènements webhook seront envoyés; longueur maximale de 255 caractères.
verify_token required string, in body	Chaîne de caractères choisie par le propriétaire de l'application pour la sécurité du client. Une chaîne identique sera incluse dans la demande de validation faite par le service d'abonnement Dokeop.

Exemple de requête

$  curl -X POST https://dokeop.com/api/v1/webhook_subscription -H "Content-Type: application/json" \
   -H "Authorization: Bearer platformtoken" \
   -d { "webhook_subscription": { "callback_url": "http://a-valid.com/callback/url", "verify_token": "123abc456efg" }}

Validation de la requête d'abonnement

Après votre demande initiale de création d'abonnement, vous recevrez une requête HTTP GET à l'adresse de rappel callback_url que vous avez fournie. La requête contiendra en paramètre un champ "hub.challenge" que vous devrez utiliser pour valider l'adresse de rappel.

Ci-dessous la liste complète des paramètres de la requête GET de validation:

hub.mode string	Il s'agira toujours de `subscribe`.
hub.challenge string	Chaîne aléatoire que l'adresse de rappel doit renvoyer pour vérifier son existence.
hub.verify_token string	Ce paramètre sera définie suivant le jeton de vérification `verify_token` transmis lors de la demande d'abonnement initiale, ce qui permet aux propriétaires d'applications de vérifier que la réponse provient bien du service d'abonnement Dokeop.

Exemple de requête de validation

$ GET http://a-valid.com/callback/url?hub.verify_token=123abc456efg&hub.challenge=18f7d1a92c1f40f8a748fd134752frt5&hub.mode=subscribe

Validation de l'adresse de rappel

Votre adresse de rappel doit répondre dans les 2 secondes à la demande GET du service d’abonnement Dokeop. La réponse doit répondre avec le code HTTP 200 OK et renvoyer le champ "hub.challenge" dans le corps de la réponse avec le type de contenu application/json: { “hub.challenge”: "18f7d1a92c1f40f8a748fd134752frt5" }

Une fois que vous avez créé avec succès un abonnement aux événements Webhook en répondant à la validation du rappel, vous recevrez une réponse à votre demande POST de création d'abonnement d'origine. Cette réponse comprendra des informations sur votre abonnement. Si la validation échoue, cette réponse inclura à la place des informations d'erreur.

Exemple de réponse à la demande d'abonnement

{
  "id": 1,
  "callback_url": "http://a-valid.com/callback/url",
  "created_at": "2019-06-28T13:49:20.257Z",
  "updated_at": "2019-06-28T13:49:20.257Z"
}

Voir un abonnement

Une demande GET https://dokeop.com/api/v1/webhook_subscription peut être effectuée pour afficher les détails de l'abonnement.

Exemple de requête

$ curl -G https://dokeop.com/api/v1/webhook_subscription \
   -H "Authorization: Bearer platformtoken"

Supprimer un abonnement

Une demande GET https://dokeop.com/api/v1/webhook_subscription peut être effectuée pour supprimer l'abonnement lié à l'application.

Les paramètres suivants doivent être inclus dans une demande de suppression :

Vous recevrez un code HTTP 204 No Content si la suppression est réussie. Sinon, une erreur sera renvoyée avec la raison de l'échec.

Exemple de requête

$ curl -X DELETE https://dokeop.com/api/v1/webhook_subscription \
   -H "Authorization: Bearer platformtoken"