Comportamenti dei webhook

Per connettere due applicazioni diverse, è possibile utilizzare i webhook. Utilizzando i webhook, è possibile configurare le notifiche degli eventi.

Un webhook è un callback HTTP. Quando si verifica un evento, un'applicazione Web che implementa i webhook trasmette i dati relativi a tale evento e li invia a un URL del webhook dall'applicazione di cui si desidera ricevere informazioni. Per ulteriori informazioni, vedere Cloud Developer Platform.

Nel contesto di VMware Cloud Director, è possibile configurare i webhook utilizzando i comportamenti dei webhook. I comportamenti dei webhook inviano una richiesta POST a un server webhook remoto. Il corpo della richiesta contiene informazioni sulla chiamata del comportamento e sull'entità in cui è stato richiamato il comportamento. È inoltre possibile personalizzare il corpo utilizzando un modello. La risposta del server webhook determina il risultato del task di chiamata del comportamento. Esistono tre diversi tipi di risposte che il server può restituire.

Il server webhook remoto può essere qualsiasi server raggiungibile da VMware Cloud Director. Tuttavia, prima di creare un comportamento webhook, è necessario verificare che l'endpoint del webhook sia sicuro.

Verificare che l'endpoint del webhook sia un endpoint HTTPS.
Verificare che l'organizzazione dell'utente che richiama il comportamento consideri attendibile il certificato del server webhook. Ciò significa che anche se il certificato è presente in un archivio di attendibilità di VMware Cloud Director, se l'organizzazione dell'utente che richiama il comportamento non considera attendibile il certificato, il comportamento del webhook non verrà eseguito.
È possibile aggiungere un certificato all'archivio di attendibilità utilizzando l'interfaccia utente o l'API di VMware Cloud Director. Vedere Gestione dei certificati.

Creazione di comportamenti dei webhook

Richiesta:

"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	Descrizione
`type`	Campo obbligatorio. Deve essere `WebHook`.
`id`	Campo stringa facoltativo.
`href`	Campo obbligatorio per l'URL che deve ricevere le richieste da VMware Cloud Director.
`_internal_key`	Campo obbligatorio per il segreto condiviso utilizzato per firmare le richieste inviate all'endpoint del webhook.
`invocation_timeout`	Campo facoltativo che specifica il timeout in secondi per la risposta dal server webhook
`template.content`	Campo facoltativo per la personalizzazione del payload inviato al server webhook. È possibile fornire un modello come stringa. È possibile aggiungere altri campi a `execution_properties`, accessibili per il modello.
`_secure_`	I campi con prefisso `_secure_` sono facoltativi. I campi sono di sola scrittura e non possono essere ottenuti tramite una richiesta GET sul comportamento. Il valore del campo viene crittografato prima di essere salvato nel database di VMware Cloud Director. I campi sono accessibili per il modello.

Payload da VMware Cloud Director al server webhook

Esiste un formato predefinito del payload inviato al server webhook. È inoltre possibile personalizzare il payload utilizzando un modello.

Esempio di payload predefinito:

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

Per i payload personalizzati con un modello, è possibile specificare un modello per il payload inviato al server webhook. Se non si specifica un modello, VMware Cloud Director invia il payload della richiesta predefinito al server webhook. Il motore del modello Apache FreeMarker esegue il rendering del payload dal modello fornito e dal modello di dati.

Il modello di dati rappresenta tutti i dati preparati per il modello, ovvero tutti i dati che è possibile includere nel payload. Il modello di dati contiene gli argomenti della chiamata del comportamento dei webhook, ad esempio argomenti, metadati, proprietà di esecuzione e informazioni sull'entità. L'esempio seguente mostra la struttura ad albero del modello di dati.

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

Tabella 1. Argomenti della chiamata
Argomento	Descrizione
`entityId`	ID dell'entità definita richiamata.
`typeId`	ID del tipo di entità dell'entità definita richiamata.
`arguments`	Argomenti passati nella chiamata del comportamento.
`arguments_string`	Stringa di argomenti in formato JSON. È possibile utilizzarla se si desidera aggiungere tutti gli argomenti al payload.
`_execution_properties`	È possibile selezionare tutti i valori dall'argomento della chiamata `execution_properties` in base al nome della chiave.
`execution`	È possibile selezionare tutti i valori dall'argomento della chiamata `execution` in base al nome della chiave.
`invocation`	È possibile selezionare tutti i valori dall'argomento `invocation` in base al nome della chiave.
`entity`	Mappa del contenuto dell'entità. È possibile selezionare tutti i valori nell'entità in base al nome della chiave.
`entity_string`	Stringa di entità in formato JSON.

Per ulteriori informazioni sul linguaggio dell'espressione di Apache FreeMarker per il modello del payload, vedere https://freemarker.apache.org/docs/dgui_quickstart_template.html.

Modello di esempio:

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

È possibile specificare intestazioni personalizzate da aggiungere alla richiesta POST inviata ai server webhook. È possibile utilizzare il modello di webhook per aggiungere intestazioni personalizzate che sono variabili nel modello con il prefisso header_. Ad esempio, è possibile specificare il valore per l'intestazione Authorization aggiungendo la riga seguente al modello:

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

Payload dal server webhook a VMware Cloud Director

Risposta predefinita
Il payload predefinito dal server webhook a VMware Cloud Director deve contenere quanto segue.
- La risposta può non avere alcuna intestazione Content-Type oppure avere un'intestazione Content-Type con valore text/plain.
- Il corpo della risposta deve essere una stringa.
- Il corpo della risposta viene utilizzato come risultato della chiamata del comportamento. Lo stato del task di chiamata del comportamento è success. Il risultato del task viene impostato sul corpo della risposta.
Risposta di aggiornamento singolo del task
Oltre al risultato del comportamento, la risposta di aggiornamento del task può impostare alcune altre proprietà del task di chiamata del comportamento come status, details, operation, error, progress e result. Poiché si tratta di un aggiornamento del task unico, la risposta deve completare il task. Se la risposta non imposta lo stato del task su success, error o aborted, il task non riesce e viene visualizzato un errore. Il messaggio di errore indica che lo stato non è accettabile.
- La risposta deve avere un'intestazione Content-Type con valore application/vnd.vmware.vcloud.task+json.
- Il corpo della risposta deve contenere una rappresentazione JSON della classe TaskType contenente le proprietà del task che si desidera modificare.
- Corpo della risposta di esempio con stato success:
```
{
   "status":"success",
   "details":"example details",
   "operation":"example operation",
   "progress":100,
   "result":{
      "resultContent":"example result"
   }
}
```
- Corpo della risposta di esempio con stato error:
```
{
   "status":"error",
   "details":"example details",
   "operation":"example operation",
   "progress":50,
   "error":{
      "majorErrorCode":404,
      "minorErrorCode":"ERROR",
      "message":"example error message"
   }
}
```
Risposta di aggiornamento continuo del task
Il server webhook può inviare più aggiornamenti del task utilizzando una risposta HTTP in più parti. Ogni aggiornamento è una parte separata del corpo della risposta. L'ultima parte del corpo della risposta del server webhook deve completare il task. Se il corpo della risposta non completa il task, il task non riesce e viene visualizzato un errore.
- La risposta deve avere un'intestazione Content-Type con valore multipart/form-data; boundary=....
- Il corpo della risposta deve iniziare e terminare con una stringa di delimitazione --<boundary_string>. Ogni parte del corpo della risposta deve terminare con una stringa di delimitazione. È necessario specificare il limite nell'intestazione Content-Type della risposta HTTP dal server 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>
```
Le parti del corpo nel corpo della risposta devono avere il formato di un aggiornamento del task o il formato di un aggiornamento finale.
Esempio di aggiornamento del task:
```
Content-Type: application/vnd.vmware.vcloud.task+json
{
"details": "example details",
"operation": "example operation",
"progress": 50
}
```
Esempio di aggiornamento finale:
```
Content-Type: text/plain
<string>
```

Autenticazione delle richieste di comportamento del webhook

L'autenticazione del codice di autenticazione del messaggio basato su hash (HMAC) protegge le richieste di comportamento del webhook. HMAC è un meccanismo che garantisce l'autenticità e l'integrità delle richieste HTTP. Per garantire l'autenticità e l'integrità, HMAC include due intestazioni personalizzate per ogni richiesta HTTP. Le intestazioni personalizzate sono un'intestazione della firma e un digest. Per VMware Cloud Director, l'intestazione della firma è x-vcloud-signature e il digest è x-vcloud-digest.

L'intestazione della firma x-vcloud-signature è un'intestazione personalizzata inviata con ogni richiesta di webhook. L'intestazione della firma è costituita da un algoritmo HMACSHA512, intestazioni e una firma generata da VMware Cloud Director. Le intestazioni mostrano il contenuto della stringa di base che è stata firmata per creare la firma.

Tabella 2. Campi dell'intestazione
Campo	Descrizione
`host`	Host del server webhook
`date`	Data della richiesta
`(request-target)`	Metodo HTTP in minuscolo collegato, spazio ASCII e intestazioni del percorso della richiesta. Ad esempio, `post /webhook`.
`digest`	Digest SHA-512 del corpo della richiesta

Per generare l'intestazione della firma, è necessario un segreto condiviso. Il segreto condiviso è una stringa nota solo a VMware Cloud Director e al server webhook.

L'intestazione del digest x-vcloud-digest è un digest SHA-512 con codifica Base64 del corpo della richiesta.

Ogni richiesta di webhook da VMware Cloud Director può essere verificata generando la firma tramite il segreto condiviso e confrontandola con la firma nell'intestazione della firma di VMware Cloud Director.

Richiamo dei comportamenti dei webhook

È possibile richiamare i comportamenti dei webhook come qualsiasi altro comportamento.

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