Triggering a Custom Action (Webhook) from a Desk.com Case

Last Updated -

Desk.com Apps allow you to use Custom Actions to notify a web-enabled resource (URL) when a rule is triggered, and send a custom message to that URL. Many people call this functionality "Webhooks", and Desk.com makes it easy for you to send a static or dynamic message to a URL of your choice. 


Setup

Go to Admin > Apps > Browse Apps, and look for Custom Action tile on the page and click on install.


Scroll down and look for Custom Action and click on Install


You'll need to know the URL of the web application that you're contacting, and whether this URL requires a user name and password (note: Desk.com Apps currently post using Basic AUTH.)  You can use RequestBin (http://requestb.in/) for testing as shown below.

 

Once the install is done, you will see Custom Action under Installed Apps. Great! Now you're ready to create an Action.


Add Custom Action

An Action is the actual message you'll be configuring to send through Desk.com to your Account when a Rule fires that matches the conditions you set. Under the Installed Apps > Custom Action click on Add Action to create a new Custom Action.
 
Then, you'll customize this action with a message. Often you will include Liquid variables to provide dynamic information about the current case:
 
 

When fired, this Action will send a message to your URL that a particular Desk.com case is updated, and provide an HTML link to let you open that case directly.


URL Encoding your JSON

Special characters to need to be escaped in JSON. If a field has the potential to get a special character, you can escape the string with the uri_encode filter. The syntax for applying a filter: {{ case.subject | uri_encode }}. For more available filters please visit the documentation.


Rules

Business rules in Desk.com allow you to act without Agent intervention when certain conditions occur at Events specified for a case. 

Here's an example rule to activate your Custom Action which will trigger on a "Case Updated" event when the case contains a specific label that you will use for this purpose. If you like, you can include the optional step also shown below that removes the label after you trigger the Custom Action to prevent the action from happening more than once:
 
 
What happens when everything works? When you update a case in Desk.com by adding the label "Send Web Action", the Rule will evaluate to be true, and the Custom Action will fire to send a message. Then, the Rule will remove the label.