Introducing the Webhooks Extension in Dovetail Carrier
We recently added a new extension to Dovetail Carrier – a Webhooks Extension.
What’s a webhook?
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 behavior 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.
Process Flow
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
This example would POST a set of JSON formatted data to the given url.
Required Message Parameters
| Parameter | Value | Comments |
| type | invokeURL | Tells Carrier to use the WebHooks Extension |
| method | Typically one of:
|
The HTTP Request Method |
| contentType | Typically one of:
|
The HTTP Request content type |
| url | https://… | The url to be invoked |
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
Advanced Options
Of course, not every web request is simple. So we also support more advanced options, including:
- Request Headers
- Windows Authentication
- Custom Authentication Functions
- JSON arrays
All of this is covered in the Dovetail Carrier Documentation.
Examples
Integrating with other apps / services using web services is pretty common now days. The Carrier Webhooks Extension makes invoking a web service pretty easy. Lets cover a few examples of where we might want to use this.
Delighted
When a case is closed, call the Delighted API to send the customer a one question survey, in order to track Net Promoter Score.
type=InvokeUrl method=POST url=https://@api.delightedapp.com/v1/people.json contentType=application/json <HEADER>.Authorization=Basic Your64bitEncodedApiKey email=[Contact Email]
Slack
When application feedback is submitted within Dovetail Agent, an Action Item is created and dispatched to a queue. When this happens, post the feedback to a Slack channel.
type=InvokeUrl method=POST url=https://hooks.slack.com/services/12345/67890/ABCDEFGHI contentType=application/json channel=#support text="Feedback Notification" username=support-bot attachments[0].fallback="Feedback Received: [Title] : [ConfigItem.Dovetail Agent URL.String]/action-items/[Action Item ID]" attachments[0].title=[Title] attachments[0].title_link="[ConfigItem.Dovetail Agent URL.String]/action-items/[Action Item ID]" attachments[0].color="warning" attachments[0].pretext="Feedback Received: [Title] " attachments[0].thumb_url="https://mycompany.com/logo.jpg" attachments[0].fields[0].title=Notes attachments[0].fields[0].value="[Notes]" attachments[0].fields[0].short=false
Twilio
Send SMS message to a customer via Twilio
type=InvokeUrl method=POST contentType=application/x-www-form-urlencoded url=https://api.twilio.com/2010-04-01/Accounts/1234567890/Messages.json <HEADER>.Authorization=" Basic MyBase64EncodedCredentials" To=[Contact Mobile Number] From=[SupportTwilioSmsNumber] Body="about case [Case ID] - [Notes Text]"
Summary
Integrating with other apps / services using web services is pretty common now days. The Carrier Webhooks Extension greatly simplifies these types of integrations.
One more tool you now have in your toolbox for making the most out of your Clarify/Dovetail system.
For even more examples of Business Rules and 3rd-party integrations, check out the Free Collection of Business Rule Recipes. There’s also a Business Rule Template, which is helpful when defining new business rules.
You can access the Business Rule Recipes and Template here.
