Webhooks

Article Overview

The following article describes EasySend's Webhooks feature. It details how to create, configure, and initialize different Webhooks.

What are Webhooks?

Webhooks are a way for web applications to transfer data in real-time to other applications or services based on event triggers. Triggers occur by performing specific actions.

EasySend and Webhooks

Webhooks are used to enable communication between digital processes/EasySign processes and external applications or services, by performing actions that trigger events and send real-time notifications. Webhooks allow EasySend users to automate workflows and ensure that essential actions taken in one system are communicated to other connected systems. 

Webhooks in EasySend

(See Figure 1 and Figure 2)

Webhooks can be found in two areas of the platform:

• Under the Integrate tab - here, you will create new Webhooks.

Figure 1: Integrate -> Webhooks

• In the Service screen - here, you will create custom Webhooks services. 

Figure 2: Services -> Webhooks

New Webhooks

(See Figure 3)

To create new Webhooks, click Integrate (1) and Webhooks (2).

Figure 3: Integrate -> Webhooks

After clicking the Webhooks option, the Webhooks screen appears.

Webhooks Screen

(See Figure 4)

Using the Webhooks screen you can create new Webhooks. Clicking the + New Webhook (1) (or Create New (1) when available) displays the Webhook Settings window.

Figure 4: Webhooks Screen

Webhook Settings Window

(See Figure 5)

The Webhook Settings window contains the following sections:

• General Settings (1) - for providing a name and description for the Webhook
• Endpoint Settings (2) - for selecting the type of Webhook to use - simple or custom
• Data transferred (3) - for selecting the payload that will be transferred once the Webhook is triggered

• Event Triggers (4) - for selecting which event will trigger the Webhook, and in some cases, which processes to associate the Webhook with.

Figure 5: Webhooks Screen

Webhook Settings Window - Endpoint Settings

(See Figure 6 to Figure 9)

This section contains a dropdown (1) with two options:

• Webhook URL - a simple Webhook
• Webhook Service - Webhook which is based on a pre-existing custom Webhook service  

Figure 6: Endpoint Settings Dropdown

When the selected option is Webhook URL (simple) you need to provide URL parameters, one URL (2), or multiple URLs for different DEV/PROD environments (3).

Figure 7: Webhook URLs

In addition to URL parameters, it is mandatory to generate a two-way secret key for the Webhook. The key will be generated by clicking the Generate Key option (4).

The Key will appear hidden (5). It must be copied and used within the external interface/service/application on the other side of the Webhook. 

Figure 8: Secret Key

If the dropdown is set to Webhook service (6) the URL and secret key parameters are no longer applicable, instead, you will select a pre-existing custom Webhook service from the Select service dropdown (7).   

Figure 9: Selecting a Custom Webhook Service

Webhook Settings Window - Data Transferred

(See Figure 10)

This section will appear only if the Webhook URL option is selected under the Endpoint section. It is used for selecting the payload that will be transferred once the Webhook is triggered:

• Webhook Data: 
  • Request Identifier (RID) 
  • WebflowId 
  • companyId
  • evetnName
  • proccessId
  • WebhookVersion
  • originalRequest - relevant only for EasySign
• Process Model:
  • End-user input data, for example:
    • First Name
    • Last Name
    • Email
  • Model Metadata, for example:
    • Browser name
    • Current time
    • Workflow step Id
  • File attachments - for both a simple and a custom Webhook only a string with the name of the file is sent and not the actual file

• Process PDFs
  • The filled-out PDFs are generated at the end of the transaction
  • The generated audit-trail PDF generated at the end of the transaction

Figure 10: Data Transferred

(See Figure 11 and Figure 12)

This section applies the Webhook to digital processes or EasySign forms and indicates when it will be triggered. It contains a Product Area dropdown (1) with two options:

• Digital Processes
• EasySign Forms

Figure 11: Event Triggers - Digital Processes

The Events dropdown (2) contains a list of event triggers that will activate the Webhook in real-time. Link Opened is the selected event by default.

When the selected Product Area is Digital Processes, a list of available business groups and processes to apply the Webhook to will appear (3). By default, all the processes are selected.  

When the selected Product Area is EasySign forms, the event trigger must be selected (4), but there is no need to select a business group or process.

Figure 12: Event Triggers - EasySign Forms

Custom Webhooks Services

(See Figure 13)

Custom Webhooks services are created by using the Service's screen Webhooks tab (1) and the + Create button (2).

Figure 13: Creating Custom Webhook Services

After clicking the + Create button the custom Webhook service screen appears.

Custom Webhook Service Screen

(See Figure 14)

The screen has three sections:

• Service name (1)

• Inputs (2)
• Steps (3)

Figure 14: Custom Webhook Service Screen

Custom Webhook Service Screen - Inputs

(See Figure 15)

This section contains the payload that will be passed to the HTTP request of the simple or custom Webhook. By default, a custom Webhook service contains the following inputs (1): 

• ProcessModel input - Model information:
  • End-user input data, for example:
    • First Name
    • Last Name
    • Email
  • Model Metadata, for example:
    • Browser name
    • Current time
    • Workflow step Id
  • Please note- that metadata is not supported for services triggered by an EasySign transaction. When setting up a Webhook service for EasySign transactions, avoid using metadata as an input source for the service.
  • File attachments - for both a simple and a custom Webhook only a string with the name of the file is sent and not the actual file 
    
• eventData - session event data, for example:
  • Request Identifier (RID) 
  • WebflowId 
  • companyId
  • evetnName
  • proccessId
  • originalRequest - relevant only for EasySign, for example:

{
    "version": "1",
    "apiKey": "1122334455",
    "customData": "Example Request 1",
    "participants": [...],
    "communication": {
        "start": [...],
        "finish": [...],
        "autoReminders": [...]
    },
    "documents": [...]
}

• pdfGenerated:
  • The filled-out PDFs are generated at the end of the transaction 
  • The audit-trail PDF generated at the end of the transaction
• webhookVersion - version of Webhooks

Figure 15: Inputs

Custom Webhook Service Screen - Steps

(See Figure 16)

A custom Webhook service can be configured with multiple steps. Each step is a different action the Integration service will perform once it is initiated. The steps are: 

• Code - writing JavaScript code
• File Storage Service - adding a step to remotely store files 
• Rest API Service - interfacing with an external service through a REST API call
• Computed Service - calculating expressions or values according to the defined conditions
• Email - sending emails as part of the integration service
• EasySend Service - adding an EasySend preconfigured event
• SQL Query - running an SQL query in an external database
• File Encode/Decode - encoding/decoding files with Base 64, Pretty Good Privacy (PGP), Rivest–Shamir–Adleman (RSA), JSON Web Encryption (JWE), and JSON Web Token (JWT)
• Salesforce Service - running Select, Create, and Update queries on any Salesforce object
• Dataverse - running Select, Create, and Update queries on any Dataverse object
• Hashing - converting to hashed hexadecimal value with a Secure Hash Algorithm (SHA), for example, SHA512

Each step has a short description of what it does and what are its inputs and outputs.

Figure 16: Steps

Important!

Any custom Webhook service must be deployed (1) to relevant environments to become active and operational. A non-deployed custom Webhook service will remain inactive. 

Usage Examples

The following sections describe common usage examples for Webhooks in EasySend:

• Transfer data from a digital process to an external website using a simple Webhook
• Transfer data from a digital process to an external website using a custom Webhook service

Simple Webhook

(See Figure 17 to Figure 23)

To use a simple Webhook to transfer data from a digital process to an external website, perform the following steps:

Figure 17: Integrate -> Webhooks

1. Click the Integrate Tab (1) and then click Webhooks (2).

         Result:

         The Webhooks screen appears:

Figure 18: Webhooks Screen

2. Click + New Webhook (3).

        Result:

         The Webhooks Settings window appears:

Figure 19: Webhooks Settings Window

3. Enter a Webhook Name (4).
4. Enter a Webhook Description (5).
5. Enter a Webhook URL (6).
6. Generate a secret key (7) and use the key with the external interface/service/application.
7. Select the data payload to transfer (8).
8. Set the product area to Digital Processes (9).
9. Select the event trigger/s (10).
10. Select the business groups and processes to apply the Webhook (11).
11. Click Save (12).
12. Initiate the digital process.

          Result:

          When the selected events occur, for example:

          Link Opened:

Figure 20: Linked Opened

          Next Page Clicked: 

Figure 21: Next Page Clicked

         Data Submitted:

Figure 22: Data Submitted

      the Webhook is triggered, and data is transferred to the external website, for example: 

Figure 23: Webhook Example

NOTE

If you selected to apply the Webhook to all processes and then created a new one, to apply the Webhook to it as well, perform a deployment from the Webhooks screen to all relevant environments.  

Custom Webhook Service with a Rest API Service Step

(See Figure 24 to Figure 45)

To use a custom Webhook service to transfer data from a digital process to an external website, perform the following steps:

Figure 24: Integrate -> Services

1. Click the Integrate tab (1) and then click Services (2).

        Result: 

        The Services screen appears:

Figure 25: Webhooks -> + Create

2. Click the Webhooks tab (3) and then click + Create (4).

        Result: 

        The custom Webhook service screen appears:

Figure 26: Webhook Service Screen

3. Enter a name for the service (5).
4. Click Add a new step (6). 

        Result: 

        A list of steps appears:

Figure 27: Rest API Service

5. Click Rest API Service (7).

       Result:        

       The following window appears:

Figure 28: Rest API Service

6. Enter a Name (8) and click Continue (9).

        Result:        

        The Rest API screen appears:

Figure 29: Rest API Screen

Figure 30: Configuring the Request Section

7. Configure the Request:
   1. Provide a Webhook URL (10).
   2. Set the Method to Post (11). 
   3. Click + Add Content Item (12) twice.

            Result:        

            Two content items appear (13):

Figure 31: Added Content Items

1. 4. Configure the content items:
      

Figure 32: Content Items Configuration

1. 1. 1. Enter the first content name - eventData (14).
      2. Set the Type to Object (15).
      3. Set the source to Model and inputs.eventData (16).
      4. Click the icon (17).

                 Result:

                 The Edit model requirements window appears:

Figure 33: Edit model requirements Window

1. 1. 5. Add the eventData items you want to transfer as part of the Webhook (18).
      6. Click Ok (19) to continue.

                 Result:

                 The Request section appears:

Figure 34: Content Items Configuration 

1. 1. 7. Enter the first content name - processModel (20).
      8. Set the Type to Object (21).
      9. Set the source to Model and inputs.processModel (22).
      10. Click the icon (23).

                 Result:

                 The Edit model requirements window appears:

Figure 35: Edit model requirements Window

1. 1. 11. Add the processModel items you want to transfer as part of the Webhook (24)
      12. Click Ok (25) to continue.

                 Result:

                 The Request section appears:

Figure 36: Services

8. Navigate back to the Services screen (26).

        Result:

        The Services screen appears:

Figure 37: Deploying the Custom Webhook Service

9. Check the custom Webhook service you created (27) and deploy (28) to the relevant environments.

Figure 38: Integrate -> Webhooks

10. After successfully finishing the deployment (29), click the Integrate tab (30) and then click Webhooks (31).

        Result:

        The Webhooks screen appears:

Figure 39: + New Webhook

11. Click +New Webhook (32).

          Result:

          The Webhooks Settings window appears:

Figure 40: Webhooks Settings Window 

12. Enter a Webhook name (33).
13. Enter a Webhook description (34).
14. Click the dropdown (35) and select Webhook Service.

         Result:

         The Webhook Settings window updates:

Figure 41: Webhooks Settings Window - Webhook Service

15. Click the dropdown (36) and select the desired Webhook service (37).
16. Set the product area to Digital Processes (38).
17. Select the event trigger/s (39).
18. Select the business groups and processes to apply the Webhook (40).
19. Click Save (41).
20. Initiate the digital process

          Result:

          When the selected events occur, for example:

          Link Opened:

Figure 42: Linked Opened

          Next Page Clicked: 

Figure 43: Next Page Clicked

         Data Submitted:

Figure 44: Data Submitted

      the Webhook is triggered, and data is transferred, for example: 

Figure 45: Webhook Example

NOTE

If you selected to apply the Webhook to all processes and then created a new one, to apply the Webhook to it as well, perform a deployment from the Webhooks screen to all relevant environments.  

Appendix A - Event Triggers Description

(See Table 1)

The appendix describes the available event triggers for a digital process and EasySign.

Table 1: Event Triggers Description