Capturing a Webhook and Creating an Email Automation in Mailsoftly

The following is an example approach and explanations for creating a workflow in Mailsoftly.

1 - Creating a Webhook Endpoint in Mailsoftly

You should first click on the Settings at the bottom of the left-hand navigation bar, then select the Company Settings option to navigate to the company settings.

After navigating to the relevant section, there are two headings of interest: API Keys and Webhook Endpoint.

The API Keys section contains keys necessary for our application to recognize incoming requests from external sources for authentication purposes.

The Webhook Endpoint, on the other hand, is a point of capture we'll use to ensure that incoming webhook requests reach us and are made usable. Let's start by clicking on the Webhook Endpoint section and proceed to create an endpoint.

When we navigate to the Webhook Endpoint page, if we have previously created any webhook endpoints, we will see a list of them, and in the top right corner, there will be a Create New Endpoint button to create a new webhook endpoint. Now, let's create a new Endpoint. Therefore, let's click on the Create New Endpoint button.


When we click on this button, an endpoint will be automatically created with a unique name. Now, let's change this name for better memorability. By clicking on the name of the endpoint, which is underlined, we can edit it in the opened field. As an example, we are changing it to Example Endpoint.


2 - Creating an API Key for Webhook Access

Now that we have created an endpoint, it means we have a point where requests can be received. However, for these incoming requests to be associated with us, we need a key. Without this API key, authentication cannot be performed. Let's create an API key now. To do this, click on the API Keys section on the left-hand side.

If you have navigated away from that page, you can proceed to the API Keys section by following Settings > Company Settings > API Keys.

After navigating to the API Keys page, let's create a new API Key using the Create Access Key button located in the top right corner.


IMPORTANT: When we click on the Create Access Key button, a window will open, showing us our API key once for us to copy. For security reasons, we won't be able to view this key again later.

Please ensure that you note down your API Key in a secure location after clicking.


3 - Providing Information to Another App that will send information to Mailsoftly

To receive a webhook request from any other application, we may need to provide our API Key and Webhook Endpoint Address to that application. At this stage, it would be correct to convey the information as follows:


Endpoint (EXAMPLE)

API Key: aF3D9Dq3********************* (EXAMPLE)


Note to third party applications: Webhook requests are only accepted as POST requests, and the API Key must be included in the Header section of the incoming request under the name Authorization.


Above, an example communication sample is provided with sample data.


Please ensure that the information you send matches your created endpoint address and that your API Key is correct.


NOTE: An endpoint can be activated with one API Key, but multiple API keys can also authenticate the same endpoint, or vice versa.

So, if you have created multiple API Keys and have multiple webhook endpoints, each one can authenticate and be used by the other. You don't need to have only one API key or use only one webhook.


4 - Creating a Workflow for Future Incoming Webhook Requests

At this stage, when we are sure that we can start receiving webhook requests (in this case, when the third party application confirms that it has made the necessary settings), we need to configure how we will handle incoming requests.

We manage incoming requests with small automation pieces under the name of workflows. To create a workflow, first, let's click on the Workflows section from the left-hand navigation and go to the page where we can manage our workflows.

After arriving at the relevant page, let's click on the Create an Endpoint Workflow button located in the top right corner. After clicking, in the window that opens, let's select the Webhook Endpoint we set up from the part labeled 'Select an Endpoint.'

As an example, we had changed its name to 'Example Endpoint.' Therefore, let's proceed by making this selection.

After making the selection, we click on the Create a Workflow button at the bottom right of the window. This will take us to an editor for creating a workflow for the selected endpoint. Through this wizard, we will be able to perform desired operations on the incoming data.


5 - Setting up Data Capture and Workflow Actions

In the editor, we will be greeted with the initial screen. Here, we can manage a trigger (in our case, a webhook) and subsequent actions. Each workflow operates with one trigger (or multiple triggers) and starts processing the added actions on the incoming data sequentially. Let's see how we can do this. When we click on the Trigger section, it will open a panel on the right side.

The panel on the right-hand side contains an example usage and information about the incoming request.

If the application we are using to send webhook request has a webhook testing interface, we can use this information there to send ourselves a test request.

Now let's see how to perform these steps.

6 - Receiving a Request from the a Third Party Application

To receive a webhook request from a third party application, after the third party application team has configured the webhook settings, we proceed to our own third party application page like a regular customer and create an action that will trigger the webhook.

After creating the appointment, if all steps are correct (Endpoint URL, API Key, and a third party application's webhook settings), we should have received a request. At this stage, we click on the 'I Sent a Request' button on the right panel to verify if the request has been received.

If the request has been successfully received, we encounter the message DATA FOUND in green color, and afterwards, we can click on the Show Captured Data button to view the received data. This allows us to get an idea of whether the received data is what we expected.

If there is an issue in the process and the data cannot reach to endpoint (this issue could be due to webhook configuration, incorrect information, or a network error), the button color turns red, and we see the message RETRY.

In this case, it's usually indicative of an error due to one of the reasons mentioned above, but still, it's possible that it might take a few minutes for the request to reach.

During this process, we can use the RETRY button to check for the data again.

7 - Determining Actions

After setting up the trigger, we can now configure the actions.

This allows us to determine what actions we can take with the incoming data and create a workflow.

To do this, let's click on the Add Event button located underneath the trigger on the left side.

When we click on the Add Event button, a new event box will be created, and we will see Select Event inside it.

To choose an action, click on the box labeled Select Event and focus on the panel on the right side to create a workflow.

In the panel on the right-hand side, in the Event Details section, let's select the event type from the dropdown box labeled Select Event Type below.

Currently, only Run a Task can be selected. Let's proceed with this choice for now.

Then, from the dropdown box that follows, we can select the desired action.

In this example, as we are going to create a draft email, we chose the Create Draft option.

After selecting the desired action, we will be prompted to enter the necessary information for that action below.

If you don't have a template design, you can click on the Create New link to access the relevant page in a new tab.

After creating your design, you can return to this tab and use the refresh button on the right side of the box to update your design pool and make your design template selectable.

To ensure that the selected template is the correct one, you can open a window to preview the design with the View Selected Template button.

Important Note: To use custom fields, as shown in the example image above, you must write your template design in Mailsoftly's custom field placeholder format, which is {(custom_field_name)}.

For example, if you are going to use a person's name as a customizable field, you should format it as Hello, {(first_name)}.


Mailsoftly will interpret any text enclosed within this format as a custom field, regardless of the content of the text, and will allow you to input data into that field.

If the selected template does not contain text in this format, you will not be able to utilize the customization feature.

After making the desired selections, we proceed to the next stage, which is data matching/personalization, by clicking the Update button.

In this section, we will be asked to match the personalized fields in our email template with the fields in the webhook data we receive.

After making these matches and ensuring the correct selections for Subject and Contact's Email Address, we click on the Finish Matching button.

This allows us to place the incoming data in the correct locations within our created emails.

Reminder: The Contact's Email Address field can be matched with data from the webhook, but you can also click on Type Manually to enter an email address manually.

However, if you enter a manual address, all resulting or sent email campaigns from processing webhook requests will go to a single individual. Therefore, we generally recommend doing this for workflows intended for notifications.

8 - Congratulations

Congratulations! Now you can click on the Save Workflow button in the top right corner to save your workflow.

You can find the email campaigns and contacts created or sent by the saved workflow in the Workflows section of the left-hand navigation.

Click on your workflow to open it, and you can find the related campaigns and contacts in the Related Campaigns and Related Contacts tabs at the top.

From there, you can send or review your desired campaign.