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 behaviour 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.
Creating Webhook Behaviors
"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.
{ "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.
+ - entityId | + - typeId | + - arguments | + - arguments_string | + - _execution_properties | + - _metadata | | | + - executionId | + - behaviorId | + - executionType | + - taskId | + - execution | | | | | + - href | + - invocation | + - invocationId | + - requestId | + - apiVersion | + - entity | + - entity_string
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.
<#assign header_Content\-Type= "application/json" /> { "text": "Behavior with id ${_metadata.behaviorId} was executed on entity with id ${entityId}" }
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 aContent-Type
header withtext/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.
- The response can either have no
- 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
, andresult
. Because this is a one-time task update, the response must complete the task. If the response does not set the task status tosuccess
,error
, oraborted
, 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 withapplication/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" } }
- The response must have a
- 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 withmultipart/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 theContent-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>
- The response must have a
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
.
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.
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
{ "arguments": { "argument1": "data1", "argument2": "data2", ... } }