Dovetail Carrier Documentation

Webhooks Extension

Webhooks are "user-defined HTTP callbacks". They are usually triggered by some event, such as pushing code to a repository or a comment being posted to a blog. When that event occurs, the source site makes an HTTP request to the URI configured for the webhook. Users can configure them to cause events on one site to invoke behaviour on another. The action taken may be anything.

This allows for making a web request based on an event within your Clarify/Dovetail system. A business rule can fire based on the event. Dovetail Rulemanager will evaluate the rule, and send a message to Dovetail Carrier. With the webhooks extension, that message can tell Carrier to make an HTTP request.

When Carrier receives a message with a type of InvokeUrl, the Webhooks Extension will process these message types.

Typically, these messages will originate from Dovetail Rulemanager (such as from a business rule action), although they can also originate from custom applications as well.

The message will specify a type of InvokeUrl, a method (POST, GET, PUT, etc.), a contentType, url, and a set of name/value pairs that are passed as parameters to the url.

Example Message

type=InvokeUrl
method=POST
contentType=application/json
url=http://api.webhookinbox.com/i/lIweTgZr/in/
param1=foo
param2=bar
param3="this is something
that has multiple lines in it
even some ""escaped"" quotation marks"

This example would POST a set of JSON formatted data to the given url.

Required Message Parameters

Parameter	Value	Comments
type	InvokeUrl	Required
method	Typically one of: GET POST PUT DELETE	The HTTP Request Method
contentType	Typically one of: application/json application/x-www-form-urlencoded	The HTTP Request content type
url		The url to be invoked

Request Headers

To specify request headers, use the <HEADER> keyword.

Examples:

<HEADER>.Accepts=application/json
<HEADER>.foo=bar
<HEADER>.Authentication=[My Custom Authentication Rule Property Function]

Windows Authentication

To specify Windows authentication for the request, simply set the UseWindowsAuth parameter to true

Example Message

type=InvokeUrl
method=POST
contentType=application/json
url=http://api.webhookinbox.com/i/lIweTgZr/in/
param1=foo
param2=bar
useWindowsAuth=true

When this flag is specified, the request will utilize the CredentialCache.DefaultCredentials value which will resolve to the Windows account being used to run the Dovetail Carrier Service.

Optional Message Parameters

Any other name/value pair defined within the message will be treated as parameters to be passed to the url.

If the method is a GET, the name/value pairs will be passed on the querystring.

If the method is POST, they will be included in the request payload.

Logging

The extension will log the details of the received message, the web request, as well as the resulting response.

Example of logs:

INFO Dovetail.Carrier.Core.RuleManager.RuleManagerConsumer -
Carrier message received:
type=InvokeUrl
method=GET
url=http://api.webhookinbox.com/i/lIwesTgZr3w/in/
foo=bar
foo2=bar2
DEBUG Carrier.Extensions.Webhooks.InvokeUrlHandler -
GET http://api.webhookinbox.com/i/lIzsTgZr/in/?foo=bar&foo2=bar2
INFO Carrier.Extensions.Webhooks.InvokeUrlHandler -
Response 200

JSON arrays

When posting JSON data, it's common to include data within arrays, and sometimes even with nested arrays.

The Webhooks Extension supports this, and makes it easy to express this syntax in a simpler fashion.

It is probably best demonstrated with an example.

For example, if a web service may require that the POSTed data be formatted like so:

{
    "channel": "#testing",
    "text": "case notification",
    "username": "testing-bot",
    "attachments": [{
        "fallback": "Case 4106 from Craig Breedlove at American Motors",
        "title": "case title goes here",
        "title_link": "https://myserver/agent/support/cases/4106",
        "color": "warning",
        "pretext": "Case 4106 from Craig Breedlove at American Motors",
        "thumb_url": "https://myserver.com/images/logo.jpg",
        "fields": [{
            "title": "Severity",
            "value": "Medium",
            "short": false
        },
        {
            "title": "Queue",
            "value": "None",
            "short": false
        },
        {
            "title": "Mobile Link",
            "value": "https://myserver.com/mobile/case/4106",
            "short": false
        }]
    }]
}

Rather than building the complex JSON formatting yourself, the Webhooks extension will do it for you,

You can express your parameters in a simpler format, like so:

type=InvokeUrl
url=https://someOtherApplication.com/api/mysecrettoken
method=POST
contentType=application/json
channel=#testing
text=case notification
username=testing-bot
attachments[0].fallback="Case 4106 from Craig Breedlove at American Motors"
attachments[0].title="case title goes here"
attachments[0].title_link="https://myserver/agent/support/cases/4106"
attachments[0].color="warning"
attachments[0].pretext="Case 4106 from Craig Breedlove at American Motors"
attachments[0].thumb_url="https://myserver.com/images/logo.jpg"
attachments[0].fields[0].title=Severity
attachments[0].fields[0].value=Medium
attachments[0].fields[0].short=false
attachments[0].fields[1].title=Queue
attachments[0].fields[1].value=None
attachments[0].fields[1].short=false
attachments[0].fields[2].title=Mobile Link
attachments[0].fields[2].value="https://myserver.com/mobile/case/4106"
attachments[0].fields[2].short=false

Take note of the attachments, attachments[index], and attachments[index].fields[index] syntax used for defining arrays and nested arrays of data.