Web Hook

ID: webhook

Makes a remote call to an HTTP endpoint.

Core Configuration

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:

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}"
            }
        },
        "branch": {
            "id": "{id}",
            "title": "{title}",
            "type": "{branchType}",
            "alias": "{alias}",
            "root-branch": "{rootBranchId}",
            "root": "{rootChangesetId}",
            "tip": "{tipChangesetId}",
            "snapshot": true|false            
        },
        "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"
}