Comportamentos de webhook do VMware Cloud Director

Para conectar dois aplicativos diferentes, você pode usar webhooks. Usando webhooks, você pode configurar notificações de eventos.

Um webhook é um retorno de chamada HTTP. Quando ocorre um evento, um aplicativo da Web que implementa webhooks transmite dados sobre esse evento e os envia para uma URL de webhook do aplicativo que você deseja que receba as informações. Para obter mais informações, consulte a Cloud Developer Platform.

No contexto do VMware Cloud Director, você pode configurar webhooks usando comportamentos de webhook. Os comportamentos do webhook enviam uma solicitação POST a um servidor webhook remoto. O corpo da solicitação contém informações sobre a invocação do comportamento e a entidade na qual o comportamento foi invocado. Você também pode personalizar o corpo usando um modelo. A resposta do servidor do webhook determina o resultado da tarefa de invocação de comportamento. Existem três tipos diferentes de respostas que o servidor pode retornar.

O servidor webhook remoto pode ser qualquer servidor que o VMware Cloud Director possa acessar. No entanto, antes de criar um comportamento de webhook, você deve verificar se o endpoint do webhook é seguro.

Verifique se o endpoint do webhook é um endpoint HTTPS.
Verifique se a organização do usuário que invoca o comportamento confia no certificado do servidor webhook. Isso significa que, mesmo se o certificado estiver presente em um repositório de confiança do VMware Cloud Director, se a organização do usuário que invoca o comportamento não confiar no certificado, o comportamento do webhook não será executado.
Você pode adicionar um certificado ao armazenamento de confiança usando a UI ou a API do VMware Cloud Director. Consulte Gerenciando certificados com o uso do seu VMware Cloud Director.

Criando comportamentos de webhook

Solicitação:

"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	Descrição
`type`	Campo obrigatório. Deve ser `WebHook`.
`id`	Campo de cadeia de caracteres opcional.
`href`	Campo obrigatório para o URL que deve receber solicitações do VMware Cloud Director.
`_internal_key`	Campo obrigatório para o segredo compartilhado usado para assinar as solicitações enviadas ao endpoint do webhook.
`invocation_timeout`	Campo opcional que especifica o tempo limite em segundos para a resposta do servidor webhook
`template.content`	Campo opcional para personalização do payload enviado ao servidor do webhook. Você pode fornecer um modelo como uma cadeia de caracteres. Você pode adicionar outros campos a `execution_properties`, acessíveis ao modelo.
`_secure_`	Os campos com o prefixo `_secure_` são opcionais. Os campos são somente gravação e não podem ser obtidos por meio de uma solicitação GET no comportamento. O valor do campo é criptografado antes de ser salvo no banco de dados do VMware Cloud Director. Os campos são acessíveis ao modelo.

Payload do VMware Cloud Director para o servidor Webhook

Há um formato padrão do payload enviado ao servidor do webhook. Você também pode personalizar o payload usando um modelo.

Exemplo de payload padrão:

{
   "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 payloads personalizados com um modelo, você pode especificar um modelo para o payload enviado ao servidor webhook. Se você não especificar um modelo, o VMware Cloud Director enviará o payload de solicitação padrão para o servidor webhook. O mecanismo de modelo Apache FreeMarker renderiza o payload do modelo de dados e do modelo fornecidos.

O modelo de dados representa todos os dados preparados para o modelo, em outras palavras, todos os dados que você pode incluir no payload. O modelo de dados contém os argumentos de invocação do comportamento do webhook, por exemplo, argumentos, metadados, propriedades de execução e informações de entidade. O exemplo a seguir mostra a estrutura semelhante a uma árvore do modelo de dados.

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

Tabela 1. Argumentos de invocação
Argumento	Descrição
`entityId`	ID da entidade definida chamada.
`typeId`	ID do tipo de entidade da entidade definida chamada.
`arguments`	Os argumentos transmitidos na invocação de comportamento.
`arguments_string`	Uma cadeia de caracteres de formato JSON de argumentos. Você poderá usá-la se quiser adicionar todos os argumentos ao payload.
`_execution_properties`	Você pode selecionar todos os valores do argumento de invocação `execution_properties` por nome de chave.
`execution`	Você pode selecionar todos os valores do argumento de invocação `execution` por nome de chave.
`invocation`	Você pode selecionar todos os valores do argumento `invocation` por nome de chave.
`entity`	Um mapa do conteúdo da entidade. Você pode selecionar todos os valores na entidade por nome de chave.
`entity_string`	Uma cadeia de caracteres de formato JSON da entidade.

Para obter mais informações sobre a linguagem de expressão do Apache FreeMarker para o modelo do payload, consulte https://freemarker.apache.org/docs/dgui_quickstart_template.html.

Modelo de amostra:

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

Você pode especificar cabeçalhos personalizados que deseja adicionar à solicitação POST enviada aos servidores webhook. Você pode usar o modelo de webhook para adicionar cabeçalhos personalizados que são variáveis no modelo com o prefixo header_. Por exemplo, você pode especificar o valor para o cabeçalho Authorization adicionando a seguinte linha ao modelo:

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

Payload do servidor Webhook para o VMware Cloud Director

Resposta padrão
O payload padrão do servidor webhook para o VMware Cloud Director deve conter o seguinte.
- A resposta não pode ter nenhum cabeçalho Content-Type ou um cabeçalho Content-Type com o valor text/plain.
- O corpo da resposta deve ser uma cadeia de caracteres.
- O corpo da resposta é usado como resultado da invocação de comportamento. O status da tarefa de invocação de comportamento é success. O resultado da tarefa é definido como o corpo da resposta.
Resposta de atualização de tarefa única
Além do resultado do comportamento, a resposta de atualização da tarefa pode definir algumas outras propriedades de tarefa de invocação de comportamento, como status, details, operation, error, progress e result. Essa é uma atualização de tarefa única, a resposta deve concluir a tarefa. Se a resposta não definir o status da tarefa como success, error ou aborted, a tarefa falhará com um erro. A mensagem de erro indica que o status não era aceitável.
- A resposta deve ter um cabeçalho Content-Type com o valor application/vnd.vmware.vcloud.task+json.
- O corpo da resposta deve conter uma representação JSON da classe TaskType contendo as propriedades da tarefa que você deseja modificar.
- Corpo de resposta de amostra com status success:
```
{
   "status":"success",
   "details":"example details",
   "operation":"example operation",
   "progress":100,
   "result":{
      "resultContent":"example result"
   }
}
```
- Corpo de resposta de amostra com status error:
```
{
   "status":"error",
   "details":"example details",
   "operation":"example operation",
   "progress":50,
   "error":{
      "majorErrorCode":404,
      "minorErrorCode":"ERROR",
      "message":"example error message"
   }
}
```
Resposta de atualização contínua da tarefa
O servidor do webhook pode enviar várias atualizações de tarefa usando uma resposta HTTP de várias partes. Cada atualização é uma parte separada do corpo da resposta. A última parte do corpo da resposta do servidor do webhook deve concluir a tarefa. Se o corpo da resposta não concluir a tarefa, a tarefa falhará com um erro.
- A resposta deve ter um cabeçalho Content-Type com o valor multipart/form-data; boundary=....
- O corpo da resposta deve começar e terminar com uma cadeia de caracteres de limite --<boundary_string>. Cada parte do corpo da resposta deve terminar em uma cadeia de caracteres de limite. Você deve especificar o limite no cabeçalho Content-Type da resposta HTTP do 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>
```
As partes do corpo no corpo da resposta devem estar no formato para uma atualização de tarefa ou no formato para uma atualização final.
Exemplo de atualização de tarefa:
```
Content-Type: application/vnd.vmware.vcloud.task+json
{
"details": "example details",
"operation": "example operation",
"progress": 50
}
```
Exemplo de atualização final:
```
Content-Type: text/plain
<string>
```

Autenticação das solicitações de comportamento do webhook

A autenticação de código de autenticação de mensagem baseada em hash (HMAC) protege as solicitações de comportamento do webhook. O HMAC é um mecanismo que garante a autenticidade e a integridade das solicitações HTTP. Para garantir a autenticidade e a integridade, o HMAC inclui dois cabeçalhos personalizados para cada solicitação HTTP. Os cabeçalhos personalizados são um cabeçalho de assinatura e um resumo. Para o VMware Cloud Director, o cabeçalho da assinatura é x-vcloud-signature e o resumo é x-vcloud-digest.

O cabeçalho de assinatura x-vcloud-signature é um cabeçalho personalizado enviado com cada solicitação de webhook. O cabeçalho de assinatura consiste em um algoritmo HMACSHA512, cabeçalhos e uma assinatura gerada pelo VMware Cloud Director. Os cabeçalhos mostram o que está na cadeia de caracteres de base assinada para criar a assinatura.

Tabela 2. Campos de cabeçalho
Campo	Descrição
`host`	O host do servidor webhook
`date`	Data da solicitação
`(request-target)`	Método HTTP minúsculo vinculado, espaço ASCII e cabeçalhos de caminho de solicitação. Por exemplo, `post /webhook`.
`digest`	Resumo SHA-512 do corpo da solicitação

Para gerar o cabeçalho da assinatura, você precisa de um segredo compartilhado. O segredo compartilhado é uma cadeia de caracteres que apenas o VMware Cloud Director e o servidor webhook conhecem.

O cabeçalho de resumo x-vcloud-digest é um resumo SHA-512 codificado em Base64 do corpo da solicitação.

Cada solicitação de webhook do VMware Cloud Director pode ser verificada gerando a assinatura usando o segredo compartilhado e comparando-a com a assinatura no cabeçalho da assinatura do VMware Cloud Director.

Invocar comportamentos de webhook

Você pode invocar comportamentos de webhook como qualquer outro comportamento.

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