How to Configure Webhooks? – Meritto

What is Webhook?

A webhook is a method of automating the flow of data between two web applications or services. It allows one application to send real-time data to another application when a specific event or trigger occurs, without the need for constant polling or manual intervention.

Event or Trigger: Webhooks are typically designed to respond to specific events or triggers. These events could be anything from a new user signing up, a payment done and submission of form.
HTTP POST Requests: Webhooks work by using HTTP POST requests to send data from the Meritto to third-party services. When the specified event occurs, an HTTP POST request containing relevant data to a URL provided by the third-party.
Payload: The data sent in the HTTP POST request is referred to as the payload. This can be in formats such as JSON and it contains information about the applicants.
Authentication and Security: To ensure that only authorized parties can send webhook notifications, authentication mechanisms such as API keys or tokens are often used.

Prerequisites to configure Webhook

As the first step, we would request you to download the Webhook Integration Kit which includes a Webhook Integration Document as well as Master Data Sheet, share it with your respective technical teams for understanding.

Please find the steps to download the Master sheet below:

Step 1: Click on Formdesk and select Manage Form (New).

Step 2: On the single action button (Gear button) option, against every form you will find the option to Download Webhook Integration Kit.

Step 3: On successful download, you will have a zip file containing the Data connect file and the Mastersheet with all necessary form fields in the system.

ERP Partners have to share their API Documents on lines as shared in the Webhook Integration Kit.

Once the API documentation follows the below steps to configure webhook.

Steps to Create a Webhook

Go to “Post Application” select “Webhook/ERP Manager” and Click on “Create”.

Create webhook.gif

Step 1: Set Webhook Config
This is the basic configuration page, where you need to choose the basic details or triggers and criteria on which the Webhook will work.

You can define the name of the Webhook based on the purpose.
You can choose the college name and form name you want to configure the Webhook.
You can also choose the trigger based on which the data should flow in the vendor ERP system.
Also, you can choose whether you want to configure a webhook at lead level or application level data. Not selecting any form will enable lead-level data to flow to the corresponding ERP system.
Vendor List selection is a mandatory one. In case you have an in-house ERP or the vendor name is not listed, please select other mention the name of the vendor, and proceed further.

Step 2: Set Webhook Template

As an industry standard, the data points between any two systems are sent and received in JSON format.
All the field tokens are listed at the top.
Details of tokens are as follows:
1. For a lead-level webhook, you can use:
  - User & Registration Tokens
2. For an application & payment webhook, you can use:
  - User & Registration Tokens
  - Form Tokens
  - Payment Tokens
3. How do you configure the template format?
  - There are 2 elements of the format:
    - Field Key at vendor end
    - Field Token within Meritto
  - Now to configure the template, use the below JSON:
    {
    "name": "{{ud.name|Registered Name}}",
    "email": "{{u.email|Registered Email}}"
    }
    where
    - name and email represent key name & email in the vendor’s ERP
    - ud.name|Registered Name and u.email|Registered Email represents field token in Meritto
    - {{ token }} → curly brackets represent that for the respective token applicant’s data will be picked dynamically from db.
4. Usually, the sample JSON is shared by the client on the data points that they want to receive at their end.
5. Upon clicking the ‘Validate JSON’ option, the system checks if there are any syntax errors before configuring the same to send the data.

Step 3: Set Webhook Conditions

Multiple conditions become mandatory while transferring data to the vendor's ERP or certain validations are required for data push. These conditions can be configured as a part of the webhook and are as follows:

Note: These configurations get enabled only once the JSON is configured on step 2. In all the below configurations (except point 7) the data will appear inside the configuration based on step 2 JSON(template format).

Required Field Configuration
- This configuration is to be used while the vendor ERP has fields with a ‘Mandatory’ condition i.e. if the field value is blank, it will not accept the request.
- Then you need to select those fields here that mandatorily need to be sent to the vendor’s ERP and a data transfer request will be made from Meritto to the vendor's ERP only once the applicant’s data has value against all the selected fields in this configuration.
Date Fields Configuration
- Make use of this config to send a different date-type field format to your ERP.
- There are approx. 17 different formats in which the date-type field data can be sent.
- For Eg. the Date type field configured in Meritto is 28/12/2023 at 11:00 PM but if you want data transfer to be done as 28/12/2023, this config can be used to make this change.

Replace Value Field Configuration
- Make use of this config to replace and send value as per your db structure.
- For Eg: For a Gender field, if you need ‘M’ instead of Male, then the same can be configured.
- What you need to do in this configuration is, select the field against which you want to replace the value and in the next box, enter the JSON in the following format - { "male": "M", "female": "F", "transgender": "T" }
- As per the above scenario, while the Male value is being captured in Meritto but at the time of data transfer ‘M’ will be sent instead of Male.

Default Value Field Configuration
- Make use of this configuration, if at your end few fields are mandatory to be sent but on Meritto the same field is configured as non-mandatory.
- Select those fields in this configuration and assign ‘null’ values against those.

Yes/No Field Configuration
- Make use of this configuration for transferring checkbox field type data.
- In Meritto, while a user consents against a checkbox type field, the consent itself is captured. In case you don’t want the entire text but need just Yes/No against this field, use this configuration.
- What you need to do here is just select all the checkbox-type fields. Now at the time of data transfer, if the applicant has selected the checkbox, Yes will be sent otherwise No will be sent.

Split Data Field Configuration
- Make use of this configuration for transferring data points after splitting it using a special character.
- For Eg. If you have captured the mobile number along with the dial code (in Meritto) in the following format i.e. +91-9999999999 and now you want to transfer only the number after ‘-’, then this configuration needs to be used.
- How to use this config?
  - Select the field against which the data needs to be split based on the special character and only partial data needs to be sent.
  - Select the operator to split the data.
  - Select the index i.e. which part of the data needs to be sent → 1 or 2.

Conditional Filter Configuration
- Make use of this configuration to transfer data based on conditions.
- For Eg. If Nationality equals x then transfer data
- Here any form field (drop-down type field only) can be used as a conditions
Integer Field Configuration
- Convert any field data into integer type and transfer data in your ERP
- For Eg. the Marks field is a text-type field but in your ERP it is an integer type. Hence you can use this configuration and transfer data
- You just need to select the field name in this configuration
File Field Configuration
- This configuration is used to transfer data to your respective folder with a designated file name
- Please note that this configuration is generally required while file upload is being done on SFTP or Amazon
- You can define the folder path and the file name structure here in this configuration against the upload file
- Sample: home/npuser/2018/NPF/production/P{{application_no}}

Step 4 : Webhook Request & Response

Here all the necessary end-points are configured in order to enable data push.
Single step is for Single API authentication (which is used for majority integrations) and Two step is where an access token needs to be generated every time for a data push.
You can select the request method, Post (GET/POST) and other necessary details.

Two-step authentication (which is used for integrations where bearer token is received in 1st step) and based on which the second api request is made
First API request configuration is as follows:

Second API request configuration is as follows:

File upload configuration, enables to send documents such as photograph, signature etc through multiple channels
- SFTP
- SFTP V4+
- Direct URL
- Amazon
- FTP

Step 5 : Preview & Test Hit

After all the necessary configurations, we need to check if the data is getting pushed successfully or not. For this, we have step 5 where we can send a test hit on the client system and check if we are receiving a successful response from the client’s end.

If a lead/application exists within the system, where the trigger and form details condition are satisfied, upon clicking the test hit option, it sends the data directly to the vendor system and fetches response of success or failure, with which we can understand if the data push is working successfully or not.