Tutorial: Setting up a generic inbound webhook (Console)
Console > Integrations > Tutorial: Setting up a generic inbound webhook (Console)
This article walks through how to set up a generic inbound webhook.
Prerequisites
This tutorial requires a basic understanding of how to use API testing tools like Postman.
Overview
In Console, you can use inbound webhooks to receive data from third-party applications. When an inbound webhook receives data, a workflow linked to the inbound webhook runs and processes the inbound data.
There are four types of inbound webhooks, classified by the type and origin of the data they transmit:
Generic inbound webhooks receive any JSON, XML, or form encoded data. Generic inbound webhooks aren’t tied to any specific third-party application (like Salesforce or Zendesk), so they can be used in a wide variety of applications.
This article covers how to create a generic inbound webhook, including:
How to create a workflow for testing, and
How to use API testing tools to verify that the inbound webhook is working correctly
Continue reading this article to learn how to set up a generic inbound webhook to transmit JSON, XML, or form data to your Avaya.cx account.
Before starting
We recommend that you read this overview article on inbound webhooks before proceeding with these steps. It will help familiarize you with inbound webhooks in general.
Part 1: Setting up a test workflow
An inbound webhook triggers a workflow to run whenever it receives data. The easiest way to determine whether an inbound webhook is working correctly is to create a test workflow that runs when the inbound webhook receives data.
For the purposes of this article, we’re using a very simple workflow with the Send SMS workflow module. The workflow will send an SMS with variables that contain data received from the inbound webhook. The goal of this exercise is to demonstrate that the webhook is sending data to the workflow and that the workflow is able to access the webhook’s data.
The example workflow is used only for testing. It sends a text message containing a firstName variable, a lastName variable, and a favoriteColor variable. These variables will be retrieved from the inbound webhook data.
Create a workflow with three modules:
Start module
Send SMS module
End module
In the Send SMS module, configure the module to send an SMS message to a phone number. This phone number should be easily accessible (like your personal cell phone number).
In the Send SMS module, configure a message that includes the following variables:
{{firstName}}
{{lastName}}
{{favoriteColor}}
See the screenshot above for an example of how this should look.
Note: The variables you enter must match exactly the name of the data sent via the webhook. For example, if the webhook receives data called firstName, the variable must also be called {{firstName}} (wrapped in curly brackets).
Publish the workflow.
Once you’ve published the workflow, continue on below to create an inbound webhook.
Part 2: Creating an inbound webhook in Console
The next step to creating an inbound webhook for processing JSON, XML, or form encoded data is to create an inbound webhook in Console.
Follow the steps in this article to learn how to create an inbound webhook: Create an inbound webhook
Note: Make sure to connect the workflow you created in Part 1 to the inbound webhook you create during this step.
Once you’ve created an inbound webhook in Console (Accounts > Integrations), return to this article to continue to Part 3 and test sending data via the webhook.
Part 3: Sending data to the inbound webhook
Once you’ve completed Part 2 above, the next step is to test sending data into your Avaya.cx account via the inbound webhook.
Note: For this section we’ll use Postman, but you can use any API testing tool you prefer.
1. Choose tour preferred API testing tool.
2. Navigate to Account > Integrations > Inbound Webhook.
3. For the webhook you have configured for generic data, click the Copy URL button. The URL is the endpoint you'll send data to for triggering the webhook to run the workflow.
4. Launch Postman and create a new, blank request.
5. Paste the URL you copied above into the URL field and make sure the HTTP method is set to POST.
6. Click the Body tab.
7. Perform one of the following based on your data format:
a. To test JSON or XML:
i. Click the raw radio button.
ii. Input properly formatted JSON or XML (see the screenshots below)
{
"firstName": "Bennie",
"lastName": "Franks",
"favoriteColor": "Yellow"
}
Example of a JSON request body
<firstName>Bennie</firstName>
<lastName>Franks</lastName>
<favoriteColor>Yellow</favoriteColor>
Example of an XML request body
b. To test form data:
i. Click the form-data radio button.
ii. Input data like the screenshot below.
8. Click Save to save the request.
9. Click the Send button to send the request.
Expected results
After clicking Send, Postman (or your preferred API testing tool) should send the JSON, XML, or form data to the URL of your inbound webhook. The inbound webhook should then run the workflow linked on the webhook.
If you created a test workflow in Part 1, you should have received a text message after executing the inbound webhook saying something along the lines of:
Hello! My name is Bennie Franks. My favorite color is Yellow.
Note that the words “Bennie”, “Franks”, and “Yellow” are derived from the variables sent via the inbound webhook.
Read more
Now that you’ve configured a simple generic inbound webhook, you’re ready to start building more complex webhooks and workflows. In this tutorial, we sent just basic data, but you can configure an inbound webhook to receive virtually any data.
Click any of the links below to learn more about inbound webhooks or about workflows to start building webhook integrations into your account.