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