Overview: Webhook workflow module (Console)

This article provides an overview of the webhook module in workflows in Console.

In this article

Overview

The webhook workflow module is a tool used for running an API request within a workflow. 

You can use the webhook module to run an API request against any REST or SOAP API (including the API Platform). 

Note: The webhook module is used for integrating with systems other than Salesforce. See our resources on integrating with Salesforce to learn how to integrate with Salesforce.

Some use cases of the webhook module include:

• Getting information about an interaction from the API Platform

• Writing or updating information in a third-party platform

• Providing a way for users to access information from a third-party platform (in coordination with the Say + Gather module)

You can configure the webhook module to save a portion of the API response body as one or more variables. This is useful when you want to pull information from an external system for use within the workflow.

Alternatively, you can set a variable if the API request should fail. This means you can have branching possibilities based on the success or failure of an API request. 

The webhook module is highly configurable, meaning there are virtually endless possibilities for integrating your account with a third-party API.

How it works

Here is a simple use case for implementing a Webhook module in your workflow:

You run a retail business where, in an attempt to draw in more sales, you want to send new subscribers to your newsletter a discount code for their first purchase. 

You manage your subscribers from a database attached to your website’s URL and use your Avaya.cx account to manage inbound interactions to handle the more routine customer inquiries like payment, tracking, etc.

You decide to set up a workflow to grow your customer base and expand your newsletter audience:

You start with a Say + Gather module to collect some of the customer’s contact information. Once you’ve collected the customer’s data, you want to know if the person is subscribed to your newsletter. So, you use a webhook module to read your database, using the customer information to look up their records.

If there’s a match, the workflow goes down the Success route, and the workflow can proceed with helping the customer with their issue. If there isn’t a match because the system wasn’t able to locate a record with the same customer information (if the customer isn’t a subscriber), the Failure route can link to a Say - Intent module to ask if they’d like to become a subscriber. If the customer agrees to become a subscriber, you use another webhook module to write the customer’s information to the database.

After writing the information to the database, you can send the customer an email with the Send Email module containing a discount code. 

This is just one example of how you could use the webhook module in a workflow to read, write, or update data on an external database.

Visual breakdown

Exterior structure

Interior structure

Below is the deep dive explanation for each interior area of the Webhook module. 

Note: When configuring this module, you’ll most likely use variables. For more information on data types and value options, refer to the variable replacement overview article. 

Data section

• Method: The Method dropdown menu is where you select the HTTP request method you want to use for the desired API resource. Refer to the API documentation of the resource to know which method to use. For API resources, see: apidocs.avaya.cx.

  • • GET: Generally used for retrieving data via an API.

    • POST: Generally used for writing data via an API.

    • PUT: Generally used for updating existing data by replacement via an API.

    • PATCH: Generally used for updating existing data by modification via an API.

    • HEAD: Generally used for simulating a GET request without actually getting the data. For example, this would be useful to get the size of a requested file before downloading it. 

    • DELETE: Generally used for deleting data via an API.

• URL: The URL field is where you put the URL of the API resource you want the webhook module to make a request to.

• Headers: The Headers field is where you include any header information in your request. This is usually where you include authentication information like a username and pass key. Please refer to the API documentation of the API you want to use to learn what headers are required.

Data section (POST, PATCH, PUT)

There are additional fields in the Data section for HTTP methods that can have a request body.

• Content Type: The Content Type dropdown menu sets the format of the request body. The webook module supports four types of content type:

  • • JSON

    • XML

    • Form Encoded

    • Form Data

Please refer to the API documentation of the API you want to use to learn what data format is most appropriate.

• Body: The Body input field is where you provide the JSON, XML, Form Encoded, or Form Data content for your request.

Advanced section

• Log Request Body: The Log Request Body toggle sets whether your Avaya.cx account makes a record of any data provided in the request body of the API request. You can access these records in the API menu in Console.

• Log Response Body: The Log Response Body toggle sets whether your Avaya.cx account makes a record of any data provided in the response body of the API response. You can access these records in the API menu in Console.

• Request Timeout (seconds): The Request Timeout (seconds) field specifies a time limit for the webhook to wait for a response for its API request. It’s generally best practice to set a request timeout so that the webhook doesn’t wait indefinitely for an API response. If the request timeout is met (if the webhook waits for the specified time and doesn’t receive a response), the module will go down the failure route.

Set Variables section

The Set Variables section is where you map values in the response body to variables that the workflow can use in later modules. You can map values either to pre-configured variables available on your account or custom variables that you create.

There are three main fields in this section:

• Name: The Name field identifies the property of the response body you want to use.

For example, you could have a JSON response body that includes an array of user objects.

{

   "users": [

       {

               "userId": 1,

               "id": 1,

               "title": "delectus aut autem",

               "completed": false

       },

       {

               "userId": 2,

               "id": 2,

               "title": "delectus aut autem",

               "completed": false

       }

   ]

}

If you wanted to target the ‘title’ value of the first item in the list, you would set the Name value to the following dot notation:

users.0.title

This notation would target the `title` field in the first item in the `users` array.

• Type: The Type dropdown field is where you select what kind of variable to map the response value to.

There are several options in this menu:

• • • Linked IDs: Used to map a value to Salesforce, Zendesk or a Custom Database.

    • Advanced: Used to map to a custom value.

    • Source: Used to map to a data value associated with the customer, like:

      • • Phone Number

        • Email

        • Person Id

        • Person Device ID

        • Person Session ID

    • Details: Used to map to various data values like:

      • • Tags

        • Comm Type

        • Recordings

        • Agent Recording

        • Caller Recording

        • Result

        • Notes

        • Points

        • Type

        • Queue

        • Contact Card URL

        • Avaya.cx User Email Address

        • Avaya.cx User First Name

        • Avaya.cx User Last Name

        • Avaya.cx User Full Name

        • Salesforce User Id

        • Zendesk User Id

    • Routing Details:

      • • Inbound Number

        • Inbound Number Name

        • Channel Key

        • Email 

    • Comm Type

      • • Phone

        • Messaging

        • Video

        • Email

        • Task

    • Variable: This can be any custom variable name that you can use later in the workflow. For more information, see: Overview: Variable replacement in workflows