Comportamientos de webhook de VMware Cloud Director

Para conectar dos aplicaciones diferentes, puede utilizar webhooks. Mediante el uso de webhooks, puede configurar notificaciones de eventos.

Un webhook es una devolución de llamada HTTP. Cuando se produce un evento, una aplicación web que implementa webhooks difunde datos sobre ese evento y los envía a una URL de webhook desde la aplicación que desea que reciba la información. Para obtener más información, consulte la Plataforma de desarrollo en la nube.

En el contexto de VMware Cloud Director, puede configurar webhooks mediante comportamientos de webhook. Los comportamientos de webhook envían una solicitud POST a un servidor de webhook remoto. El cuerpo de la solicitud contiene información sobre la invocación del comportamiento y la entidad en la que se invocó el comportamiento. También puede personalizar el cuerpo mediante una plantilla. La respuesta del servidor webhook determina el resultado de la tarea de invocación de comportamiento. Existen tres tipos diferentes de respuestas que el servidor puede devolver.

El servidor de webhook remoto puede ser cualquier servidor al que puede acceder VMware Cloud Director. Sin embargo, antes de crear un comportamiento de webhook, debe comprobar que el endpoint del webhook sea seguro.

Compruebe que el endpoint de webhook sea un endpoint HTTPS.
Compruebe que la organización del usuario que invoca el comportamiento confía en el certificado del servidor de webhook. Esto significa que, incluso si el certificado está presente en un almacén de confianza de VMware Cloud Director, si la organización del usuario que invoca el comportamiento no confía en el certificado, el comportamiento de webhook no se ejecutará.
Puede agregar un certificado al almacén de confianza mediante la interfaz de usuario o la API de VMware Cloud Director. Consulte la Administrar certificados con VMware Cloud Director.

Crear comportamientos de webhook

Solicitud:

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


Campo	Descripción
`type`	Campo obligatorio. Debe ser `WebHook`.
`id`	Campo de cadena opcional.
`href`	Campo obligatorio para la URL que debe recibir solicitudes de VMware Cloud Director.
`_internal_key`	Campo obligatorio para el secreto compartido utilizado para firmar las solicitudes enviadas al endpoint de webhook.
`invocation_timeout`	Campo opcional que especifica el tiempo de espera en segundos para la respuesta del servidor de webhook
`template.content`	Campo opcional para la personalización de la carga útil enviada al servidor de webhook. Puede proporcionar una plantilla como una cadena. Puede agregar otros campos a `execution_properties`, accesibles para la plantilla.
`_secure_`	Los campos con el prefijo `_secure_` son opcionales. Los campos son de solo escritura y no se pueden obtener a través de una solicitud GET sobre el comportamiento. El valor del campo se cifra antes de guardarse en la base de datos de VMware Cloud Director. La plantilla puede acceder a los campos.

Carga útil de VMware Cloud Director para el servidor de webhook

Existe un formato predeterminado de la carga útil que se envía al servidor de webhook. También puede personalizar la carga útil mediante una plantilla.

Ejemplo de carga útil predeterminada:

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

Para las cargas útiles personalizadas con una plantilla, puede especificar una plantilla para la carga útil que se envía al servidor de webhook. Si no especifica una plantilla, VMware Cloud Director envía la carga útil de solicitud predeterminada al servidor de webhook. El motor de plantillas Apache FreeMarker procesa la carga útil de la plantilla proporcionada y el modelo de datos.

El modelo de datos representa todos los datos preparados para la plantilla, es decir, todos los datos que se pueden incluir en la carga útil. El modelo de datos contiene los argumentos de invocación del comportamiento del webhook (por ejemplo, argumentos, metadatos, propiedades de ejecución e información de entidad). El siguiente ejemplo muestra la estructura de árbol del modelo de datos.

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

Tabla 1. Argumentos de invocación
Argumento	Descripción
`entityId`	Identificador de la entidad definida invocada.
`typeId`	Identificador del tipo de entidad de la entidad definida invocada.
`arguments`	Los argumentos pasados en la invocación del comportamiento.
`arguments_string`	Una cadena de argumentos en formato JSON. Puede usarlo si desea agregar todos los argumentos a la carga útil.
`_execution_properties`	Puede seleccionar todos los valores del argumento de invocación `execution_properties` por nombre de clave.
`execution`	Puede seleccionar todos los valores del argumento de invocación `execution` por nombre de clave.
`invocation`	Puede seleccionar todos los valores del argumento `invocation` por nombre de clave.
`entity`	Un mapa del contenido de la entidad. Puede seleccionar todos los valores de la entidad por nombre de clave.
`entity_string`	Una cadena de formato JSON de entidad.

Para obtener más información sobre el lenguaje de expresiones de Apache FreeMarker para la plantilla para la carga útil, consulte https://freemarker.apache.org/docs/dgui_quickstart_template.html.

Plantilla de muestra:

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

Puede especificar los encabezados personalizados que desea agregar a la solicitud POST enviada a los servidores de webhook. Puede utilizar la plantilla de webhook para agregar encabezados personalizados que son variables en la plantilla con el prefijo header_. Por ejemplo: puede especificar el valor del encabezado Authorization agregando la siguiente línea a la plantilla:

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

Carga útil del servidor de webhook para VMware Cloud Director

Respuesta predeterminada
La carga útil predeterminada del servidor de webhook para VMware Cloud Director debe contener lo siguiente.
- La respuesta no puede tener un encabezado Content-Type o puede tener un encabezado Content-Type con el valor text/plain.
- El cuerpo de la respuesta debe ser una cadena.
- El cuerpo de la respuesta se utiliza como resultado de la invocación del comportamiento. El estado de la tarea de invocación de comportamiento es success. El resultado de la tarea se establece como el cuerpo de la respuesta.
Respuesta de actualización de tarea única
Además del resultado del comportamiento, la respuesta de actualización de la tarea puede establecer otras propiedades de la tarea de invocación de comportamiento, como status, details, operation, error, progress y result. Debido a que se trata de una actualización de tarea única, la respuesta debe completar la tarea. Si la respuesta no establece el estado de la tarea como success, error o aborted, se produce un error en la tarea. El mensaje de error indica que el estado no es aceptable.
- La respuesta debe tener un encabezado Content-Type con el valor application/vnd.vmware.vcloud.task+json.
- El cuerpo de la respuesta debe contener una representación JSON de la clase TaskType que contenga las propiedades de la tarea que desea modificar.
- Cuerpo de respuesta de ejemplo con estado success:
```
{
   "status":"success",
   "details":"example details",
   "operation":"example operation",
   "progress":100,
   "result":{
      "resultContent":"example result"
   }
}
```
- Cuerpo de respuesta de ejemplo con estado error:
```
{
   "status":"error",
   "details":"example details",
   "operation":"example operation",
   "progress":50,
   "error":{
      "majorErrorCode":404,
      "minorErrorCode":"ERROR",
      "message":"example error message"
   }
}
```
Respuesta de actualización de tarea continua
El servidor de webhook puede enviar varias actualizaciones de tareas mediante una respuesta HTTP de varias partes. Cada actualización es una parte independiente del cuerpo de la respuesta. La última parte del cuerpo del cuerpo de la respuesta del servidor de webhook debe finalizar la tarea. Si el cuerpo de la respuesta no finaliza la tarea, se produce un error en la tarea.
- La respuesta debe tener un encabezado Content-Type con el valor multipart/form-data; boundary=....
- El cuerpo de la respuesta debe comenzar y terminar con una cadena de límite --<boundary_string>. Cada parte del cuerpo de la respuesta debe terminar en una cadena de límites. Debe especificar el límite en el encabezado Content-Type de la respuesta HTTP del servidor 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>
```
Las partes del cuerpo en el cuerpo de la respuesta deben tener el formato para una actualización de tarea o el formato para una actualización final.
Ejemplo de actualización de tarea:
```
Content-Type: application/vnd.vmware.vcloud.task+json
{
"details": "example details",
"operation": "example operation",
"progress": 50
}
```
Ejemplo de actualización final:
```
Content-Type: text/plain
<string>
```

Autenticación de las solicitudes de comportamiento de webhook

La autenticación mediante código de autenticación de mensajes basada en hash (HMAC) protege las solicitudes de comportamientos de webhook. HMAC es un mecanismo que garantiza la autenticidad y la integridad de las solicitudes HTTP. Para garantizar la autenticidad y la integridad, HMAC incluye dos encabezados personalizados en cada solicitud HTTP. Los encabezados personalizados son un encabezado de firma y un resumen. Para VMware Cloud Director, el encabezado de firma es x-vcloud-signature y el resumen es x-vcloud-digest.

El encabezado de firma x-vcloud-signature es un encabezado personalizado que se envía con cada solicitud de webhook. El encabezado de firma consta de un algoritmo HMACSHA512, encabezados y una firma generada por VMware Cloud Director. Los encabezados muestran lo que hay en la cadena base que está firmada para crear la firma.

Tabla 2. Campos de encabezado
Campo	Descripción
`host`	El host del servidor de webhook
`date`	Fecha de la solicitud
`(request-target)`	Método HTTP en minúscula vinculado, espacio ASCII y encabezados de ruta de solicitud. Por ejemplo, `post /webhook`.
`digest`	Resumen SHA-512 del cuerpo de la solicitud

Para generar el encabezado de firma, necesita un secreto compartido. El secreto compartido es una cadena que solo VMware Cloud Director y el servidor de webhook conocen.

El encabezado de resumen x-vcloud-digest es un resumen SHA-512 del cuerpo de la solicitud codificado en Base64.

Cada solicitud de webhook de VMware Cloud Director se puede verificar generando la firma con el secreto compartido y comparándola con la firma existente en el encabezado de firma de VMware Cloud Director.

Invocar comportamientos de webhook

Puede invocar comportamientos de webhook como cualquier otro comportamiento.

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