Custom Webhook

A webhook is an automated message that is sent to an external application when an event occurs. On a more technical level, a webhook is an HTTP callback request generated by an event notification. This HTTP request is logged as a webhook URL and is used to store data in JSON format.

To set up a webhook, the client gives us a unique URL to the server API and specifies through our platform which event it wants to know about. Once the webhook is set up, the server will automatically send the relevant payload to the client's webhook URL when the specified event occurs.

Therefore, Webhook HTTP requests are a specific subset of HTTP requests which transfer data between systems based on events in those systems.

A webhook HTTP request generally consists of the following:

• Start line (Method, URL)
• Header(s)
• Body (payload)

By enabling the Custom Webhook custom integration, your endpoint must have an access method and receive a JSON body. The steps to integrate it into the platform are:

1. Select the Custom Webook card from the pane.
2. Select Next.

You will be taken to a window that addresses the details of the Custom Webhook integration, as shown.

There are two configuration steps, the Custom Webhook Information and the other with the platform communication channels to be used in the solution, identified as Connections.

Custom Webhook Information

From the Custom Webhook Information section, type the following information:

1. Alias: Type a custom name to identify the Custom Webhook.

2. Method & URL: Each request has a single start line. It comes at the beginning of the request and includes the

   Method: Request methods (verbs) define the action performed by an HTTP request. At present, our platform supports four HTTP methods: POST, GET, PUT, DELETE.

   URL: You must provide us with the following URL structure:

3. The Custom Webhook is divided by four components:

• Params

  URL parameters (known also as “query parameters”) are a defined set of parameters attached to the end of a url. They are extensions of the URL that are used to help define specific content or actions based on the data being passed.

  To identify a URL parameter, refer to the portion of the URL that comes after a question mark (?). URL parameters are made of a key and a value, separated by an equal sign (=). Multiple parameters are each then separated by an ampersand (&).

  A URL with query parameters looks like this:

📘

NOTE

This information will register the webhooks for receiving messages on the remote server.

Let's configure the following query parameters to the URL structure as an example :

https//

To add query parameters to the URL, select the Add Field button from the Query Params tab. In the Key and Value columns, define the key-value parameters that are sent as part of the webhook request. From the Type column select Text or Variable depending the type of information you desire to receive in your webhook.

• Auth: Webhooks use authentication to securely integrate with their destination systems and signing secrets to verify the integrity of their requests.

  Webhooks support three types of authentication: API Key, Basic, and Bearer Token.

  To add the Webhook Authentication type, select the Type dropdown menu and click on the type of authentication your Webhook requires from the Auth tab.

In case your Webhook does not require authentication, select the No Authentication option from the Type dropdown menu.

• Headers: You can specify custom headers that the platform will use while sending the payload to the specified webhook endpoint. Headers for a webhook HTTP request may either be default (standard) headers or custom headers.

  Many headers are default and are automatically generated by the source system. Here are a few default headers commonly used with webhooks:

  Content-Type: Describes the data sent in the body (example: application/json)
  Content-Length: Defines the size of the request in bytes.

  The headers use key-value parameters that are sent as part of the webhook request. The values of these key-value pairs are visible and editable in the webhook editor. And, you are able to delete the key-value by selecting the Delete icon located in the Actions tab.

  To add query parameters to the URL, select the Add Field button from the Headers tab. In the Key and Value columns, define the key-value parameters that are sent as part of the webhook request. From the Type column select Text or Variable depending the type of information you desire to receive in your webhook.

  As Header example, the following headers key-value will be sent with all requests:

• Body: The body of a webhook HTTP request contains the data sent via POST (in most cases) or sometimes PUT or PATCH.

  The URL typed is the external callback where the events of the message will be registered and published. That is, the following example parameters sent to your callback URL will be the events to be recorded in the callback once the end users begin to participate in your campaign:

📘

NOTE

For nested fields use dot notation (key.child)

For Array fields use square bracket notation (key[ ])

If you want to receive additional parameters in your webhook, select the Add Field button.

In case you don't want to receive one or more of the predefined parameters mentioned above in your webhook, select the Delete icon located in the Actions tab.

Connections

The next step is to select the platform channels that will be used for the interactions. This is done in Connections. In it, there is a pull-down menu that will offer the channels in the platform that can be used to establish the channels through which the Custom Webhook integration will be used. A sample screenshot is shown below.

📘

NOTE

If you want to engage (integrate) Custom Webhook with a Chatbot Service campaign, do not add any connections to the Custom Webhook.

The channels to be used in the Custom Webhook integration cannot be shared with the platform Keyword or Chatbot type campaigns as it would create an operational conflict.

Actually you are able to add two types of channel connections:

• SMS texting

• WhatsApp

In the future, we are going to add more channel connections to the Custom Webhook integration.

To configure the connecting channels,

1. Select the desired connection from the Available Connections dropdown menu. The left side of the connection corresponds to the channel type and the right side corresponds to the connection code.

2. Select the Add + button to add the connection.

Repeat this step for every channel that is part of the integration. The platform will include the selected channels in the table immediately below the menu.

Once both, the Custom Webhook Information and the Connections are defined, select Save.

In case you are integrating Custom Webhook to a Chatbot Service campaign, just enter the required fields to complete the Custom Webhook information without adding any connection and select Save.

Follow these steps, to enable the Custom Webhook integration according to the configuration set up (with and without connections) when you added the integration:

Custom Webhook with Connections

The saved integration will be shown under the Integrations tab as a card, where you can view the values used in the integration for the Alias, URL, Integration Id, the connection and API details (Detail icon), and the options to delete, edit or activate it (Actions icon).

The next step is to activate the integration, done by selecting Start ▶. The integration card will be modified to show its active state, displaying the connection icons in blue.

By Selecting the Details Icon in the card, will show the channel and number/code (sender) associated with that connection from the Connections Details tab.

By selecting the API Details tab, will show the URL Endpoint along with Headers, Paramters, Responses. From the Try Out tab, the URL must be used to send response events to chats initialized by the contact. To make use of this URL, a chat initialized by the contact to which you want to provide support must already exist.

Once the integration is active, Stop under Actions, will return it to the inactive state.

Custom Webhook Integration with Chatbot Service

Once you've added the Custom Webhook integration without including any connections, the next step is to enable the integration between Custom Webhook and Chatbot Service campaign.

The saved integration will be shown under the Integrations tab as a card, where you can view the values used in the integration for the Alias, URL, Integration Id, API details (Detail icon), and the options to delete, edit or activate it (Actions icon).

The next step is to activate the integration, done by selecting Start ▶. The integration card will be modified to show its active state to enable.

Once enabled the Custom Webhook integration from the Integrations tab, the next step is integrate the Chatbot campaign and Custom Webhook. To know how to configure a chatbot campaign that will contain the Custom Webhook integration previously defined, go to the Chatbot Service section.

📘

NOTE

The Custom Webhook integration must be Active to be associated with a Chatbot Service campaign.

After creating the Chatbot service and enabling it in Live status, the integration card will be modified to show its active state, displaying the Detail icon.

By selecting the Campaigns icon, you will be able to see which campaigns the Custom Webhook integration is linked to.

It will display a dialog with the following information:

At the top of the dialog displays the integration type.

• Campaign Id: Unique identifier of the campaign.
• Campaign Name: Name of the campaign.
• Integration Date: Date when creating the campaign linked to the integration and enabling it in Live status.

By selecting the API Details tab, will show the URL Endpoint along with Headers, Parameters, Responses. From the Try Out tab, the URL must be used to send response events to chats initialized by the contact. To make use of this URL, a chat initialized by the contact to which you want to provide support must already exist.

Considerations

If the OpenAI integration is linked to any campaigns, you will not be able to pause (stop) the integration. If you try to pause it, a dialog will be displayed mentioning that it is invalid the action required.

The steps to remove the OpenAI integration associated with campaigns are the following:

1. To remove the Custom Webhook integration, you must first disable the campaigns that the integration is linked to. To do it, go to the Live campaigns associated with the Custom Webhook integration. Then, select the Report button and click on the Pause button. It will display a dialog to confirm the action, select the Confirm button.

2. Finally, go back to the Integrations tab from the References section and select the Pause button.

   In case you want to delete the integration, select the Delete icon from the Actions buttons.