Web Hook

ID: webhook

Makes a remote call to an HTTP endpoint.

Core Configuration

Property Type Required Default Description
url text true The fully-qualified HTTP endpoint (i.e. http://www.myserver.com/endpoint)
method text false The HTTP method to invoke (default: POST)
username text false The Basic authentication username.
password text false The Basic authentication password.
payload object false The JSON payload for PUT and POST calls.
headers object false The headers to apply to the HTTP call.
params object false The HTTP request parameters (query string) to be applied to the HTTP call.

Signatures

When web hook calls are made with a JSON payload, you can optionally configure them to include an HTTP header that is a digest of the content of the payload. The digest is computed using a hashing algorithm of your preference and using a secret key known only by the Web Hook action and the receiver.

When the receiver gets the JSON payload, it can take the value of the HTTP header and compare it to the value it gets by locally hashing the JSON payload it receives. These should match. If they match, then it can be asserted that the invocation came from the Cloud CMS API server's Web Hook action. If they do not match or if the HTTP header is missing, then the invocation could be considered invalid (either invoked from something other than the ClouD CMS API Web Hook action or manipulated by a man-in-the-middle attack).

To use this, you must supply the following:

Property Type Required Default Description
signatureType text false HMAC_MD5 Identifies the hashing algorithm to apply to the JSON payload to compute the hash.
signatureKey text true The secret key used to seed the hash algorithm. This secret should only be known by the Web Hook action and the receiver code. The hashed value of the JSON payload and the HTTP header should compared and should match for valid invocations.
signatureHeader text false X-CLOUDCMS-SIGNATURE The name of the HTTP header that should contain the server-side generated digest.

Request ID

Each web hook call will receive a request ID. If the method is GET or DELETE, the request ID will be in a request parameter called _requestId. Otherwise, it will be available in the JSON payload.

Policy QName

If the web hook action is connected to a rule that is triggered from a policy firing, then the QName of the policy that was triggered will be supplied either with the payload or as a request parameter (for GET or DELETE methods). The request parameter, if supplied, is called _policyQName.

Payloads

POST and PUT web hooks will receive a payload similar to this.

{
    "_cloudcms": {
        "requestId": "{requestId}"
        "platformId": "{platformId}",
        "node": {
            "repositoryId": "{repositoryId}",
            "branchId": "{branchId}",
            "id": "{id}",
            "changesetId": "{changesetId}",
            "changesetRev": "{changesetRev}",
            "object": {
                ... node properties
            },
            "paths": {
                "root": "{path}"
            }
        },
        "projects": [{
            "id": "{projectId}",
            "title": "{projectTitle}",
            "type": "{projectType}"
        }],
        "user": {
            "domainId": "{domainId}",
            "id": "{id}",
            "name": "{name}",
            "email": "{email}",            
        },
        "policy": {
            "qname": "{policyQName}"
        }
    },
    ... additional custom properties
}

The Policy QName describes the event which occurred against the described node that triggered the web hook (if any). If the action was triggered ad-hoc or via some custom code, this policy may not be available. But if the action was triggered by a rule, then it will always be available.

The Node information includes changeset details so that you can track which transaction the node committed.

The User is the current user who executed the action or the activity that led to a policy-bound rule triggering the action.

The Projects array contains information about any projects that this node belongs to. In most cases, this will be an array of size 1 (or size 0 if the Node's Repository does not belong to a Project).

Node paths are calculated for you and provided in the paths object. This provides file/folder paths back to the root or mount points in the repository.

Web Hook Server

Cloud CMS provides a sample web hook server in the Cloud CMS SDK:

https://github.com/gitana/sdk/tree/master/webhook-server

Sample Configurations

A web hook call to a simple POST handler

{
    "method": "POST",
    "url": "https://internal.mycompany.com/endpoint"
}

A web hook call with Basic authentication

{
    "method": "POST",
    "url": "https://internal.mycompany.com/endpoint",
    "username": "joe",
    "password": "joeisawesome1234"
}

A web hook call (PUT) with headers, params and some payload values that are included

{
    "method": "PUT",
    "url": "https://internal.mycompany.com/endpoint",
    "headers": {
        "token": "abcdef1234"
    },
    "params": {
        "action": "invalidate"
    },
    "payload": {
        "source": "cloudcms"
    }
}

A web hook call (POST) that sends a digest in the HTTP header called "MY_DIGEST"

{
    "method": "POST",
    "url": "https://internal.mycompany.com/endpoint",
    "signatureType": "HMAC_MD5",
    "signatureKey": "abcdef12345",
    "signatureHeader": "MY_DIGEST"
}