This article is for web developers who want to use the WebHooks feature of Automation to pass on information from CX Social to another web application. It requires that you are familiar with automation recipes in CX Social.
Further more, it requires that your pricing plan includes the automation workflows feature. Contact us at email@example.com for more information on the WebHooks feature or if you would like to use it for your account.
What is a WebHook?
With a WebHook, data can be send from one web application to an other, typically this data is sent after a certain event/action happens in the first application.
In this case CX Social is the first application, which sends a HTTP request to a specific URL with specific parameters, where it is then 'caught' by the other application. The actions triggering the WebHook are incoming mentions matching certain criteria, filters or smart tags, defined in the Automation recipes as usual. More about automation recipes in CX Social.
How to trigger a WebHook from CX Social
1. Choose the action that triggers the WebHook
Go to Settings > Automation, and create or edit an Automation Recipe. In the first part of the recipe, you define when the recipe should be triggered. You can choose that the recipe is triggered with every new mention in a topic, or only for mentions matching certain conditions.
2. Choose your the Name and Description of your WebHook
In the second part of the recipe, select the 'Trigger a WebHook' option. In the menu that opens, you can give your WebHook a name and a description.
3. Choose your desired HTTP Verb
Next, you can choose which HTTP Verb you want to use: either a POST or a GET request. These Hypertext Transfer Protocols are enabling the communication between clients and servers.
- The GET Verb (with name and values) is sent in the URL of a GET requests. Thus these requests can be bookmarked, have length restrictions and shouldn't be used with sensitive data.
- The POST Verb (with name and values) is sent in the HTTP message body of the POST request. These POST requests do not remain in the browser history, do not have restrictions on length and are never cached.
Note: If you don't understand the difference between the POST and GET Requests, it's probably better to choose the POST Verb. This one is a little safer than GET since it does not store parameters in browser history or in web server logs. Again, the data isn't displayed in URLs either.
4. Define your URL
Next you can define the URL of your WebHook. This URL is defined by the service you want to send the WebHook to. You can use the properties of the mentions in the URL that trigger the WebHook. You can for example include the ID of the mention that triggered the WebHook in the URL. All possible variables are listed below the input field. There you have the option as well to read more about these variables.
Including data in the POST body
When you choose to use the POST Request as a HTTP Verb, you have the option to send extra data along in the Request Body of the WebHook. Therefor you can use properties of the mention. This is possible using 'dot' syntax e.g. [mention.author.name] or [mention.source.url].
Click the green buttons below the input field to automatically insert mention properties in the URL or POST body.To receive all available properties of a mention, simply insert [mention] in the POST body text input area (either by clicking the green button for it or typing manually), like this:
Next, we will send all properties of the mention in JSON encoded format, and your WebHook will receive a string formatted like this example: