Skip to main content
Cartegraph Campus

About Webhooks

You must have administrator rights to access this feature.

This feature may not be available in every package. Not sure if you have this feature or you want to learn more about it? Send us a message at support@cartegraph.com.

Webhooks are used to connect two different applications. When an event occurs in the first application, the first application serializes data about the event and sends it to a webhook URL that is exposed in the second application. Cartegraph is able to do both incoming and outgoing webhooks, or the first application mentioned in the webhooks definition. 

In Cartegraph, webhooks are built using an automation block. The webhook block is found everywhere the Send Email block is found, scheduled automation blocks, and notify triggers. Incoming webhooks use the incoming webhooks trigger. Like any other automation, you can configure the trigger conditions for the automation. 

Outgoing Webhooks  

  1. Paste in the URL you want called in the other application. 
  2. Select the Record Source to indicate which Cartegraph record you want to send.  

In the rare case that the other application requires authentication to call the webhook, you can turn on the Use Basic Authentication toggle and enter the user name and password. These values are encrypted and stored in Cartegraph. 

Cartegraph works with apps like Zapier and IfThisThenThat for building webhooks. For sending tweets, a Twilio account is required. 

Incoming Webhooks Trigger

When creating an automation for incoming webhooks, you will use the Incoming Webhook trigger, which triggers the automation by a remote application. 

A new URL is uniquely generated.  You can use the Copy button to the right of the URL and then paste that URL into the other application. When a specific event occurs in the other application, the other application will serialize data about the event into a Json message and will then send that Json message to this URL.  OMS will route the message to this automation. 

The remote application will have an option to test the URL. You can click the Capture button on our UX and you will see a countdown as OMS temporarily allows this URL to be available. Then click the Test button in the other application and a sample of the message displays in the Example Body field if the test is successful.

The example body text is normally not modified and contains five properties: 

  1. A text property named Issue 
  2. An integer property named Address Number 
  3. A text property named Street 
  4. A date/time property named Date 
  5. A text property named Notes 

These five properties are made available to the blocks in the body of your automation.

5 webhook properties.png

When you turn on the new automation, the URL is made active. If the other application invokes the URL, your new automation will run. If the automation is turned off, the URL is no longer valid.

Details

The remote application should use an http post to call the incoming webhook URL. The message body should be a valid Json. If the Json message contains an array [ ], then the automation is invoked once for each element in the array.

Prune

The Prune field is optimal and is normally left blank. Consider the following example:

Prune example.png

In the message above, the example body has five top-level properties that will be made available: Issue, Address Number, Street, Date, and Notes. The three properties nested in the Requestor branch of the Json are not available. 

If you would like to focus your automation on these three properties instead of the five top-level properties, then you need to prune the Json tree down to the appropriate Requestor node. In this case, you would enter Requestor in the Prune field and then click the Capture button along with the Test button in the other application to recapture your example body. 

Now the Json message from the remote application has been pruned to the appropriate branch and your example body should look like this:

Pruned.png

Advanced

Occasionally, the remote system might format dates in a UNIX format as an integer representing the number of seconds or milliseconds since January 1, 1970.

Since Jan 1 1970.png

By default, the incoming webhook interprets the number as an integer instead of as a date.

To fix this, after capturing the example body, replace the large integer with one of these two strings, being careful to keep the double quotes around the value. Using these two strings tells the incoming webhook to process the property as a date/time rather than as an integer.

"_CG_UNIX_MILLISECONDS_"  If your integer value has 13 digits
"_CG_UNIX_SECONDS_" If your integer value has 10 digits

Your example body will now process correctly and should now look like this:

Example body.png

  • Was this article helpful?