Implementing a Webhook Handler

A webhook is a mechanism that some cloud applications use to push out (near) real-time notifications to external systems. It works by issuing an HTTP POST to an external web service.  This is useful when you want to be notified when certain events occur in your applications, or if you need to send information to another system.  Because webhooks are fired only when certain events occur, it eliminates the need to use polling and other less efficient techniques.

There is no standard for Webhooks.  Applications implement webhooks in different ways.   Some applications post the event name and an object id, requiring subsequent API calls back to the cloud application to retrieve the datea. Others will post the entire object as request parameters, XML, or JSON.

itDuzzit Support for Webhooks

Several applications in our Duzzit Library support webhooks including:

• Autotask (they call them “callouts”)
• FreshBooks
• Formstack
• Lighthouse
• Nexmo
• Wufoo
• Twilio
• Zendesk (“triggers”)

itDuzzit is perfect for creating webhook handlers because:

1. itDuzzits solutions (duzzits) are hosted securely
2. Any duzzit can be exposed as an API by simply clicking a checkbox
3. itDuzzit can natively process XML and JSON
4. itDuzzit’s drag-and-drop editor gives you access to any other cloud application as well as e-mail and SMS.

How to Create a Webhook Handler Using itDuzzit

To demonstrate an itDuzzit webhook handler, we’ll use the Lighthouse ticketing system. We’ll create a duzzit to send a text message whenever a new ticket is created. Lighthouse does not currently have a user interface for adding, deleting, and listing webhooks. So we created some duzzits to perform these functions. To use them, you’ll have to connect your itDuzzit account to Lighthouse on the itDuzzit connections page.

To begin, create a duzzit with an input value named “http-request-body”. When Lighthouse calls our webhook, it will post a JSON object to our duzzit. The JSON object will go into this input field. Specify the datatype of JSON and paste in a sample of the JSON that will get posted. I ran this a couple of times to see what was posted and then collected the sample to paste in.

{
 "version": {"creator_name":"steve (at itduzzit)",
  "permalink":"ticket-for-project2",
  "number":1,
  "user_name":"steve (at itduzzit)",
  "milestone_id":null,"created_at":"2011-04-13T16:57:42Z",
  "body_html":"<div><p>Test</p></div<",
  "title":"Ticket for Project2",
  "body":"Test",
  "url":"http://itduzzit.lighthouseapp.com/projects/1/tickets/1",
  "updated_at":"2011-04-13T16:57:44Z",
  "project_id":11111,
  "diffable_attributes":{
    "state":"new"
  },
  "closed":false,
  "tag":null,
  "priority":1,
  "attachments_count":0,
  "creator_id":144000,
  "version":4,
  "user_id":144000,
  "assigned_user_id":null,
  "state":"new"
 }
}

After pasting in the sample data and saving my input value, I created an output called “Message” and checked the “Store the Output Value” checkbox.  This will cause the value to get saved to the itDuzzit logs. Now the JSON structure shows up on the left of the Duzzit Editor.  I can drag fields from the JSON on the left into the main logic area of my duzzit.  I created an “IF” to check if the version/version value is equal to “1″, which indicates that this is a new ticket.

I want to send a message using SMS so I drag fields from the left into my message:

New ticket # [[${json:object.version/number}]]
[[${json:object.version/url}]]

Then I select Send SMS from the “Send” menu and I drop that into my “IF”. I select my mobile number (which I set on the itDuzzit account page) by clicking “(select value)” and selecting it under “Account User Values” and then I use the message output variable.

The final setup step is turning this duzzit into an API and then registering the webhook with Lighthouse. On the settings page, I checked the box to enable the duzzit to be run as an API.  I also gave my duzzit a nice URL.

When I register the webhook, I’ll have to use a URL that includes my itDuzzit API token so that when it runs, it will have access my itDuzzit account.  I can use the Lighthouse Create Callback duzzit to register the webhook and then use the Lighthouse Callback List duzzit to verify that it was registered.

Now, if someone creates a ticket in Lighthouse, I get a text message.  I can check the logs page or use the “View History” link to see that Lighthouse called my duzzit.

If you want to try this out yourself, you can start by copying the one I created.