REQUEST A DEMO

WebHooks in Clarify/Dovetail

What is a WebHook?

From the WebHooks wiki:webhooks

The concept of a WebHook is simple. A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST.

A web application implementing WebHooks will POST a message to a URL when certain things happen. When a web application enables users to register their own URLs, the users can then extend, customize, and integrate that application with their own custom extensions or even with other applications around the web. For the user, WebHooks are a way to receive valuable information when it happens, rather than continually polling for that data and receiving nothing valuable most of the time. WebHooks have enormous potential and are limited only by your imagination! (No, it can’t wash the dishes. Yet.)

That sounds like a business rule (in Clarify speak)

Why yes, it does sound like a business rule. When an event happens, and certain conditions are met, we want to fire an action. For a webhook, the action is an HTTP request. 

How can we make an HTTP request from a business rule?

A common way to make HTTP requests is by use of cURL. So we can call cURL directly, or if needed, wrap it in a script.

Simple Example

Here’s an example business rule that calls cURL directly:

Object Type: Case
Rule Name/Description: WebHook example
Start Event: Dispatch
Cancel Events:
Conditions: none
Action Title: call URL
Action Type: Command Line
Start Action: 0 minutes
From: Event Creation
Using: Elapsed Time
Repeat: Never 
Message: curl.exe http://company.com/someurl?caseId=[Object ID]

So when the event happens (a case is dispatched), an HTTP request will be made to the defined URL.

Callling cURL directly is fine when the URL is simple. When it gets more complex, I’d move it into a script.

Slightly more complex example

Here’s an example that sends a message to Campfire using the Campfire API when a case is dispatched.

Note: This is pulled right out of our production system. We do indeed send messages to Campfire when events happen in our Dovetail system.

The script (campfire-speak.bat):

@echo off
SET room=12345
SET token=myPrivateCampfireSecurityToken
SET message="{"message":{"body": "%1" }}"

curl -u %token%:X -H "Content-Type:application/json" -d %message%
http://mycampfire.campfirenow.com/room/%room%/speak.json

And here’s a rule that calls that script:

Object Type: Case
Rule Name/Description: Campfire notification
Start Event: Dispatch
Cancel Events:
Conditions: none
Action Title: Notify Campfire
Action Type: Command Line
Start Action: 0 minutes
From: Event Creation
Using: Elapsed Time
Repeat: Never 
Message:

c:campfire-speak.bat "[Object Type] [Object ID] has been dispatched to the [Current Queue] queue"

What if MakeHttpRequest was a first-class action type in Business Rules?

One of things Kevin and I were kicking around today was making a new business rule action type of MakeHttpRequest. This would allow for the business rule action to look like:

Action Title: call URL
Action Type: MakeHttpRequest
Start Action: 0 minutes
From: Event Creation
Using: Elapsed Time
Repeat: Never 
Message: http://company.com/someurl&caseId=[Object ID]

This simplifies things a little, but not a whole lot. We could change Rulemanager to support this pretty easily – we’re just not sure if it’s worth it. (If you care to chime in on this, please leave a comment).

Where can I read more about WebHooks?

Summary

Pretty easy – no?

So the next time you hear some über geek talk about webhooks, you now know what they’re talking about, and how easy it is to use them in your Clarify / Dovetail system.

Rock on.