Comportements des Webhooks

Pour connecter deux applications différentes, vous pouvez utiliser des Webhooks. En utilisant des webhooks, vous pouvez configurer des notifications d'événements.

Un Webhook est un rappel HTTP. Lorsqu'un événement se produit, une application Web implémentant des Webhooks diffuse des données sur cet événement et les envoie à une URL Webhook à partir de l'application dont vous souhaitez recevoir les informations. Pour plus d'informations, reportez-vous à Cloud Developer Platform.

Dans le contexte de VMware Cloud Director, vous pouvez configurer des Webhooks à l'aide de comportements Webhook. Les comportements Webhook envoient une demande POST à un serveur Webhook distant. Le corps de la demande contient des informations sur l'appel de comportement et l'entité sur laquelle le comportement a été appelé. Vous pouvez également personnaliser le corps en utilisant un modèle. La réponse du serveur Webhook détermine le résultat de la tâche d'appel de comportement. Le serveur peut renvoyer trois types de réponses.

Le serveur Webhook distant peut être n'importe quel serveur accessible par VMware Cloud Director. Cependant, avant de créer un comportement de Webhook, vous devez vérifier que le point de terminaison du Webhook est sécurisé.

Vérifiez que le point de terminaison Webhook est un point de terminaison HTTPS.
Vérifiez que l'organisation de l'utilisateur qui appelle le comportement approuve le certificat du serveur Webhook. Cela signifie que même si le certificat est présent dans un magasin d'approbations VMware Cloud Director, si l'organisation de l'utilisateur qui appelle le comportement n'approuve pas le certificat, le comportement Webhook ne s'exécutera pas.
Vous pouvez ajouter un certificat au magasin d'approbations à l'aide de l'interface utilisateur ou de l'API VMware Cloud Director. Reportez-vous à la section Gestion des certificats.

Création de comportements Webhook

Demande :

"POST https"://host/cloudapi/1.0.0/interfaces/<interface_id>/behaviors{
   "name":"webhookBehavior",
   "execution":{
      "type":"WebHook",
      "id":"testWebHook",
      "href":"https://hooks.slack.com:443/services/T07UZFN0N/B01EW5NC42D/rfjhHCGIwzuzQFrpPZiuLkIX",
      "key":"secretKey",
      "execution_properties":{
         "template":{
            "content":"<template_content_string>"
         },
         "_secure_token":"secureToken",
         "invocation_timeout":7
      }
   }
}


Champ	Description
`type`	Champ requis. Doit être `WebHook`.
`id`	Champ de chaîne facultatif.
`href`	Champ obligatoire pour l'URL qui doit recevoir les demandes de VMware Cloud Director.
`_internal_key`	Champ obligatoire pour le secret partagé utilisé pour signer les demandes envoyées au point de terminaison Webhook.
`invocation_timeout`	Champ facultatif spécifiant le délai d'expiration en secondes pour la réponse du serveur Webhook
`template.content`	Champ facultatif pour la personnalisation de la charge utile envoyée au serveur Webhook. Vous pouvez fournir un modèle sous forme de chaîne. Vous pouvez ajouter d'autres champs à `execution_properties`, accessible au modèle.
`_secure_`	Les champs ayant le préfixe `_secure_` sont facultatifs. Les champs sont en écriture seule et ne peuvent pas être obtenus via une demande GET sur le comportement. La valeur du champ est chiffrée avant d'être enregistrée dans la base de données VMware Cloud Director. Les champs sont accessibles au modèle.

Charge utile de VMware Cloud Director vers le serveur Webhook

Il existe un format par défaut de la charge utile envoyée au serveur Webhook. Vous pouvez également personnaliser la charge utile à l'aide d'un modèle.

Exemple de charge utile par défaut :

{
   "entityId":"urn:vcloud:entity:vmware:test_entity_type:b95d96ec-c294-4a64-b5c4-9009abe6ab06",
   "typeId":"urn:vcloud:type:vmware:test_entity_type:1.0.0",
   "arguments":{
      "x":7
   },
   "_metadata":{
      "executionId":"testWebHook",
      "execution":{
         "href":"https://webhook.site/3ca4588f-c9f1-4c0f-911f-734ab598b2dc"
      },
      "invocation":{
         
      },
      "apiVersion":"36.0",
      "behaviorId":"urn:vcloud:behavior-interface:webhookBehavior:vmware:test_interface_3:1.0.0",
      "requestId":"8312df21-712c-4b85-86d4-c9b00669662f",
      "executionType":"WebHook",
      "invocationId":"115c5b99-09e8-44f7-8189-4b9d96e067b1",
      "taskId":"a9e0556b-7699-4ded-b56b-c51fee659008"
   },
   "entity":{
      "cluster":{
         "name":"testCluster0"
      },
      "clusterState":{
         "host":"testHost",
         "status":"valid"
      }
   }
}

Pour les charges utiles personnalisées avec un modèle vous pouvez spécifier un modèle pour la charge utile envoyée au serveur Webhook. Si vous ne spécifiez pas de modèle, VMware Cloud Director envoie la charge utile de demande par défaut au serveur Webhook. Le moteur de modèle Apache FreeMarker restaure la charge utile à partir du modèle fourni et du modèle de données.

Le modèle de données représente toutes les données préparées pour le modèle, c'est-à-dire toutes les données que vous pouvez inclure dans la charge utile. Le modèle de données contient les arguments d'appel du comportement du Webhook, par exemple, les arguments, les métadonnées, les propriétés d'exécution et les informations sur l'entité. L'exemple suivant montre la structure de type arborescence du modèle de données.

+ - entityId 
|
+ - typeId 
|   
+ - arguments
|  
+ - arguments_string 
|
+ - _execution_properties 
|                      
+ - _metadata
|   |
|   + - executionId
|   + - behaviorId
|   + - executionType
|   + - taskId
|   + - execution 
|   |   |
|   |   + - href
|   + - invocation 
|   + - invocationId
|   + - requestId
|   + - apiVersion
|  
+ - entity 
|
+ - entity_string

Tableau 1. Arguments d'appel
Argument	Description
`entityId`	ID de l'entité définie appelée.
`typeId`	ID du type d'entité de l'entité définie appelée.
`arguments`	Arguments transmis dans l'appel de comportement.
`arguments_string`	Chaîne d'arguments au format JSON. Vous pouvez l'utiliser si vous souhaitez ajouter tous les arguments à la charge utile.
`_execution_properties`	Vous pouvez sélectionner toutes les valeurs à partir de l'argument d'appel de `execution_properties` par nom de clé.
`execution`	Vous pouvez sélectionner toutes les valeurs à partir de l'argument d'appel de `execution` par nom de clé.
`invocation`	Vous pouvez sélectionner toutes les valeurs à partir de l'argument `invocation` par nom de clé.
`entity`	Carte du contenu de l'entité. Vous pouvez sélectionner toutes les valeurs de l'entité par nom de clé.
`entity_string`	Chaîne au format JSON de l'entité.

Pour plus d'informations sur le langage d'expression Apache FreeMarker pour le modèle de la charge utile, reportez-vous à la page https://freemarker.apache.org/docs/dgui_quickstart_template.html.

Exemple de modèle :

<#assign header_Content\-Type= "application/json" />
{
"text": "Behavior with id ${_metadata.behaviorId} was executed on entity with id ${entityId}"   
}

Vous pouvez spécifier des en-têtes personnalisés que vous souhaitez ajouter à la demande POST envoyée aux serveurs Webhook. Vous pouvez utiliser le modèle de Webhook pour ajouter des en-têtes personnalisés qui sont des variables dans le modèle avec le préfixe header_. Par exemple, vous pouvez spécifier la valeur de l'en-tête Authorization en ajoutant la ligne suivante au modèle :

<#assign header_Authorization = "${_execution_properties._secure_token}" />

Charge utile du serveur Webhook vers VMware Cloud Director

Réponse par défaut
La charge utile par défaut du serveur Webhook vers VMware Cloud Director doit contenir les éléments suivants.
- La réponse peut ne pas avoir d'en-tête Content-Type ou un en-tête Content-Type avec la valeur text/plain.
- Le corps de la réponse doit être une chaîne.
- Le corps de la réponse est utilisé comme résultat de l'appel de comportement. L'état de la tâche d'appel de comportement est success. Le résultat de la tâche est défini sur le corps de la réponse.
Réponse de mise à jour de tâche unique
Outre le résultat du comportement, la réponse de mise à jour de la tâche peut définir d'autres propriétés de tâche d'invocation de comportement, telles que status, details, operation, error, progress et result. Il s'agit d'une mise à jour de tâche ponctuelle. La réponse doit terminer la tâche. Si la réponse ne définit pas l'état de la tâche sur success, error ou aborted, la tâche échoue avec une erreur. Le message d'erreur indique que l'état n'était pas acceptable.
- La réponse doit avoir un en-tête Content-Type avec la valeur application/vnd.vmware.vcloud.task+json.
- Le corps de la réponse doit contenir une représentation JSON de la classe TaskType contenant les propriétés de la tâche que vous souhaitez modifier.
- Exemple de corps de réponse avec l'état success :
```
{
   "status":"success",
   "details":"example details",
   "operation":"example operation",
   "progress":100,
   "result":{
      "resultContent":"example result"
   }
}
```
- Exemple de corps de réponse avec l'état error :
```
{
   "status":"error",
   "details":"example details",
   "operation":"example operation",
   "progress":50,
   "error":{
      "majorErrorCode":404,
      "minorErrorCode":"ERROR",
      "message":"example error message"
   }
}
```
Réponse de mise à jour de tâche continue
Le serveur Webhook peut envoyer plusieurs mises à jour de tâches à l'aide d'une réponse HTTP en plusieurs parties. Chaque mise à jour est une partie distincte du corps de la réponse. La dernière partie du corps de la réponse du serveur Webhook doit terminer la tâche. Si le corps de la réponse ne termine pas la tâche, la tâche échoue avec une erreur.
- La réponse doit avoir un en-tête Content-Type avec la valeur multipart/form-data; boundary=....
- Le corps de la réponse doit commencer et se terminer par une chaîne de délimitation --<boundary_string>. Chaque partie du corps de la réponse doit se terminer par une chaîne de limite. Vous devez spécifier la limite dans l'en-tête Content-Type de la réponse HTTP du serveur Webhook.
```
Headers:
...
Content-Type: multipart/form-data; boundary=<boundary_string>

Body: 
--<boundary_string>
Content-Type: application/vnd.vmware.vcloud.task+json
{                             
"details": "example details",                      
"operation": "example operation",
"progress": 50
}
--<boundary_string>
Content-Type: application/vnd.vmware.vcloud.task+json
{
"status": "success",
"progress": 100,
"result": {
"resultContent": "example result"
}
}
--<boundary_string>
```
Les parties du corps de la réponse doivent être au format pour une mise à jour de tâche ou au format pour une mise à jour finale.
Exemple de mise à jour de tâche :
```
Content-Type: application/vnd.vmware.vcloud.task+json
{
"details": "example details",
"operation": "example operation",
"progress": 50
}
```
Exemple de mise à jour finale :
```
Content-Type: text/plain
<string>
```

Authentification des demandes de comportement Webhook

L'authentification par code d'authentification de message basée sur le hachage (HMAC) sécurise les demandes de comportement Webhook. HMAC est un mécanisme qui garantit l'authenticité et l'intégrité des demandes HTTP. Pour garantir l'authenticité et l'intégrité, HMAC inclut deux en-têtes personnalisés à chaque demande HTTP. Les en-têtes personnalisés sont un en-tête de signature et un résumé. Dans VMware Cloud Director, l'en-tête de signature est x-vcloud-signature et l'en-tête de signature est x-vcloud-digest.

L'en-tête de signature x-vcloud-signature est un en-tête personnalisé envoyé avec chaque demande de Webhook. L'en-tête de signature se compose d'un algorithme HMACSHA512, d'en-têtes et d'une signature générée par VMware Cloud Director. Les en-têtes affichent le contenu de la chaîne de base qui est signée pour créer la signature.

Tableau 2. Champs d'en-tête
Champ	Description
`host`	L'hôte du serveur Webhook
`date`	Date de la demande
`(request-target)`	Méthode HTTP en minuscules liées, espace ASCII et en-têtes de chemin de demande. Par exemple, `post /webhook`.
`digest`	Résumé SHA-512 du corps de la demande

Pour générer l'en-tête de signature, vous avez besoin d'un secret partagé. Le secret partagé est une chaîne que seuls VMware Cloud Director et le serveur Webhook connaissent.

L'en-tête de résumé x-vcloud-digest est un résumé SHA-512 codé en Base64 du corps de la demande.

Vous pouvez vérifier chaque demande Webhook à partir de VMware Cloud Director en générant la signature à l'aide du secret partagé et en la comparant à la signature dans l'en-tête de signature de VMware Cloud Director.

Appel des comportements Webhook

Vous pouvez appeler des comportements Webhook comme n'importe quel autre comportement.

{
"arguments": {
"argument1": "data1",
"argument2": "data2",
...
 }
}