Thursday, July 28, 2016

Starting vRO Workflows with Log Insight Webhooks

Beginning with version 3.3 of Log Insight, alerts can be forwarded via a webhook.  Basically, any URL you designate will have an HTTP POST issued with the alert contents as a JSON body.  This feature provides some very basic capability and most use cases will require a bit more functionality.

For example, vRO workflows can be started from the vRO REST API, but you need to authenticate and prepare a JSON body with expected inputs at a minimum.

I learned of a nice shim, written in Python by some of my peers here at VMware.  You can read more about the general capability of the shim at this link.  The shim had the basic capability I needed, it just didn't support a vRO endpoint.  The authors (Alan Castonguay and Steven Flanders) invited contributions via a pull request, so, I added the vRO shim and I want to provide a little more information about the usage here in this blog post.  General install and usage instructions are on the Github page for the shim, so I won't cover that.


The "" shim does not include any authentication information.  By default, Requests library defaults to the user's .netrc file if no auth options are given.  So, you will need to set up a .netrc in the user home directory with the hostname, username and password, i.e.

machine vro-01a.corp.local
login administrator@vsphere.local
password VMware1!

This has the benefit of securing the password without adding additional code and exposing the credentials.

To Parse or Not to Parse?

The example code shows a workflow that accepts two inputs, both string.  One is "value" which I will talk about below in the next section.  The other, "alertName" is a value that can be retrieved via the parse() function that is part of the main file "" and does a nice job of returning a Python object that you can pull various bits of the alert payload from.  

Do you need to use the parsed alert?  Depends.  In the use case I was writing this shim for, I needed the entire payload in vRO so I could parse it there.  This is because the alert itself has a lot of variability - it is an alert that watches for NSX distributed firewall drops on port 22, by src/dst pair.  That src/dst pair could be different each time and there could be any number of those pairs in a single alerts - practically impossible to anticipate for workflow input.  On the other hand, if your alert watches a specific system for a specific event... well, you probably don't even need to pass inputs. Or maybe you just need the system name.  My recommendation is to try and make your Log Insight alerts as specific as possible and then deal with the remaining variables in either the Python code via the parse() function or in the case of multiple variables by passing the entire alert payload on to vRO for evaluation.

JSON Payload Serialization

I ran into a fun problem with trying to pass a JSON string to vRO as an input.  Basically, it confuses vRO because it reads the JSON string input value as part of the parameter input body.  My work-around was to serialize the JSON string from Log Insight and as such vRO would just see a long string input and be happy.

So, this is why you see the line:

"value": base64.b64encode(request.get_data())

As discussed above, you might not need to do this.  However, if you do, you'll want to grab the CyrptoJS actions package for vRO It has a base64 decode action and I tested it with the shim.

Comments and feedback are welcome, of course.  The shim is provided as an example and should not be used in production.


  1. Hi John,

    I followed the procedure on but I keep getting a 401 response every time the shim sends the request to vRO:

    2017-07-17 20:39:39,623 INFO URL=
    2017-07-17 20:39:39,624 INFO Headers={'Content-type': 'application/json'}
    2017-07-17 20:39:39,624 INFO Body={"parameters": [{"name": "alertId", "scope": "local", "type": "string", "value": {"string": {"value": "6f2d0b2a-e566-4d7b-bdc6-602d9b31c37b"}}}]}
    2017-07-17 20:39:39,624 INFO Check=False
    2017-07-17 20:39:39,628 DEBUG Starting new HTTPS connection (1):
    /root/webhook-shims/venv-webhookshims/lib/python2.7/site-packages/urllib3/ InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised. See:
    2017-07-17 20:39:39,658 DEBUG "POST /vco/api/workflows/891596b4-c5a5-4bf2-ac26-bbb20090ae15/executions HTTP/1.1" 401 1154
    2017-07-17 20:39:39,660 INFO - - [17/Jul/2017 20:39:39] "POST /endpoint/vro/891596b4-c5a5-4bf2-ac26-bbb20090ae15/6f2d0b2a-e566-4d7b-bdc6-602d9b31c37b HTTP/1.1" 401 -

    I found this information as well on the vRO Swagger:

    "Single Sign-On Authentication
    If Orchestrator is configured with the vCenter Single Sign-On (SSO) server, you need a principal holder-of-key (HoK) token to access system objects in Orchestrator through the REST API.
    The HoK token is passed as a request Authorization header element. The value must be gzip, base64
    encoded string.

    To be able to test the service bellow you need to enable basic authentication over sso.
    This happens by adding the following property to configuration file:

    com.vmware.o11n.sso.basic-authentication.enabled = true "

    I added the line to the vRO config and restarted the appliance, now I can send requests using Swagger using the syntax user@domain, but still no luck with the shim.

    In your example here the syntax is administrator@vsphere.local, same as I have it on the netrc file. Are you aware or any other requirements?, do I need a HoK token to make this work?

    Thank you,


    1. Juan, can you open an issue on the github repo for webhook shims? This will allow others to respond and we can track this. Thanks!