To connect two different applications, you can use webhooks. By using webhooks, you can set up event notifications.

A webhook is an HTTP callback. When an event happens, a web application implementing webhooks broadcasts data about that event and sends it to a webhook URL from the application that you want to receive the information. For more information, see the Cloud Developer Platform.

In the context of VMware Cloud Director, you can configure webhooks by using webhook behaviors. Webhook behaviors send out a POST request to a remote webhook server. The body of the request contains information about the behavior invocation and the entity the behavior was invoked on. You can also customize the body by using a template. The webhook server response determines the result of the behavior invocation task. There are three different types of responses that the server can return.

The remote webhook server can be any server that VMware Cloud Director can reach. However, before creating a webhook behavior, you must verify that the endpoint of the webhook is secure.

  • Verify that the webhook endpoint is an HTTPS endpoint.
  • Verify that the organization of the user invoking the behavior trusts the webhook server certificate. This means that even if the certificate is present in a VMware Cloud Director trust store, if the organization of the user, who invokes the behavior does not trust the certificate, the webhook behavior will not run.
  • You can add a certificate to the trust store by using the UI or the VMware Cloud Director API. See Managing Certificates Using Your VMware Cloud Director.

Creating Webhook Behaviors

Request: 
"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
      }
   }
}
Field Desciption
type Required field. Must be WebHook.
id Optional string field.
href Required field for the URL that must receive requests from VMware Cloud Director.
_internal_key Required field for the shared secret used for signing the requests sent to the webhook endpoint.
invocation_timeout Optional field specifying the timeout in seconds for the response from the webhook server
template.content Optional field for customization of the payload sent to the webhook server. You can provide a template as a string. You can add other fields to execution_properties, accessible to the template.
_secure_ Fields with prefix _secure_ are optional. The fields are write-only and cannot be obtained through a GET request on the behavior. The field value gets encrypted before it is saved to the VMware Cloud Director database. The fields are accessible to the template.

Payload From VMware Cloud Director to the Webhook Server

There is a default format of the payload sent to the webhook server. You can also customize the payload by using a template.

Default payload example: 
{
   "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"
      }
   }
}

For custom payloads with a template, you can specify a template for the payload sent to the webhook server. If you do not specify a template, VMware Cloud Director sends the default request payload to the webhook server. The Apache FreeMarker template engine renders the payload from the provided template and the data model.

The data model represents all the data prepared for the template, in other words, all the data that you can include in the payload. The data model contains the invocation arguments of the webhook behavior, for example, arguments, metadata, execution properties, and entity information. The following example shows the tree-like structure of the data model. 
+ - entityId 
|
+ - typeId 
|   
+ - arguments
|  
+ - arguments_string 
|
+ - _execution_properties 
|                      
+ - _metadata
|   |
|   + - executionId
|   + - behaviorId
|   + - executionType
|   + - taskId
|   + - execution 
|   |   |
|   |   + - href
|   + - invocation 
|   + - invocationId
|   + - requestId
|   + - apiVersion
|  
+ - entity 
|
+ - entity_string
Table 1. Invocation arguments
Argument Description
entityId ID of the invoked defined entity.
typeId ID of the entity type of the invoked defined entity.
arguments The arguments passed in the behavior invocation.
arguments_string A JSON format string of arguments. You can use it if you want to add all the arguments to the payload.
_execution_properties You can select all the values from the execution_properties invocation argument by key name.
execution You can select all the values from the execution invocation argument by key name.
invocation You can select all the values from the invocation argument by key name.
entity A map of the entity content. You can select all values in the entity by key name.
entity_string A JSON format string of entity.

For more information on the Apache FreeMarker expression language for the template for the payload, see https://freemarker.apache.org/docs/dgui_quickstart_template.html.

Sample template: 
<#assign header_Content\-Type= "application/json" />
{
"text": "Behavior with id ${_metadata.behaviorId} was executed on entity with id ${entityId}"   
}
You can specify custom headers that you want to add to the POST request sent to the webhook servers. You can use the webhook template for adding custom headers which are variables in the template with the prefix header_. For example, you can specify the value for the Authorization header by adding the following line to the template: 
<#assign header_Authorization = "${_execution_properties._secure_token}" />

Payload From the Webhook Server to VMware Cloud Director

  • Default response
    The default payload from the webhook server to VMware Cloud Director must contain the following.
    • The response can either have no Content-Type header or a Content-Type header with text/plain value.
    • The response body must be a string.
    • The body of the response is used as the result of the behavior invocation. The status for the behavior invocation task is success. The task result is set to the body of the response.
  • Single task update response
    Apart from the behavior result, the task update response can set some other behavior invocation task properties like status, details, operation, error, progress, and result. Because this is a one-time task update, the response must complete the task. If the response does not set the task status to success, error, or aborted, then the task fails with an error. The error message indicates that the status was not acceptable.
    • The response must have a Content-Type header with application/vnd.vmware.vcloud.task+json value.
    • The response body must contain a JSON representation of the TaskType class containing the task properties you want to modify.
    • Sample response body with status success:
      {
   "status":"success",
   "details":"example details",
   "operation":"example operation",
   "progress":100,
   "result":{
      "resultContent":"example result"
   }
}
    • Sample response body with status error:
      {
   "status":"error",
   "details":"example details",
   "operation":"example operation",
   "progress":50,
   "error":{
      "majorErrorCode":404,
      "minorErrorCode":"ERROR",
      "message":"example error message"
   }
}
  • Continuous task update response
    The webhook server can send multiple task updates by using a multi-part HTTP response. Each update is a separate body part of the response body. The last body part of the webhook server response body must finish the task. If the response body does not finish the task, the task fails with an error.
    • The response must have a Content-Type header with multipart/form-data; boundary=... value.
    • The response body must start and end with a boundary string --<boundary_string>. Each part of the response body must end in a boundary string. You must specify the boundary in the Content-Type header of the HTTP response from the webhook server. 
      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>

    The body parts in the response body must be in the format for a task update or the format for a final update.

    Task update example: 
    Content-Type: application/vnd.vmware.vcloud.task+json
{
"details": "example details",
"operation": "example operation",
"progress": 50
}
    Final update example: 
    Content-Type: text/plain
<string>

Authentication of the Webhook Behavior Requests

Hash-based message authentication code (HMAC) authentication secures webhook behavior requests. HMAC is a mechanism ensuring the authenticity and integrity of HTTP requests. To ensure the authenticity and integrity, HMAC includes two custom headers to each HTTP request. The custom headers are a signature header and a digest. For VMware Cloud Director, the signature header is x-vcloud-signature and the digest is x-vcloud-digest.

The signature header x-vcloud-signature is a custom header sent with each webhook request. The signature header consists of an HMACSHA512 algorithm, headers, and a VMware Cloud Director generated signature. The headers show what is in the base string which is signed to create the signature.
Table 2. Header Fields
Field Description
host The webhook server host
date Date of the request
(request-target) Linked lowercase HTTP method, ASCII space, and request path headers. For example, post /webhook.
digest SHA-512 digest of the request body

To generate the signature header, you need a shared secret. The shared secret is a string that only VMware Cloud Director and the webhook server know.

The digest header x-vcloud-digest is a Base64-encoded SHA-512 digest of the request body.

Each webhook request from VMware Cloud Director can be verified by generating the signature using the shared secret and comparing it to the signature in the signature header from VMware Cloud Director.

Invoking Webhook Behaviors

You can invoke webhook behaviors like any other behavior. 
{
"arguments": {
"argument1": "data1",
"argument2": "data2",
...
 }
}