User Permissions: You must be an Admin in FreeAgent to access Webhooks and Workflows
In this article, we will cover the following topics:
- What are Webhooks
- Webform considerations
- FreeAgent CRM and Webhooks
- Integrate your Webform with FreeAgent
What Are Webhooks?
Webhooks allow two web applications to communicate with each other. So for instance, if someone submits a “Contact Us” form on your website, you can send that data to your FreeAgent Account to get the new contact created.
In technical terms, webhooks are user-defined HTTP callbacks that are triggered by an event in a source system and then sent to the destination system.
This means when an event or trigger takes place on your website, automated messages are sent to a connected service. A trigger can be anything like a blog comment, product purchase, user registrations, or form submissions.
Webform Considerations
- There are different options you can choose from depending on your host and platform.
- When the form is submitted, the webform provider will send back an email with the information that was filled out.
- Verify that the plugin for your web form has webhook options. Most popular web platforms provide support for webhooks. Some examples are:
- If the plugin of your web form provider does not have webhook options you can also integrate your web form through Email Parser by Zapier.
- Often times pricing on web forms is dependent on the number of monthly submissions.
FreeAgent CRM and Webhooks
You can use webhooks to send or retrieve information between FreeAgent CRM and other external tools. There are a variety of uses for webhooks. Examples of popular use cases for webhooks include:
- Retrieving data from another system to create or update your FreeAgent CRM records.
- Posting FreeAgent CRM contacts data to another system.
- Sending deal data to an external system to create a purchase order.
Webhooks are incredibly useful for developers and tech-savvy FreeAgent CRM users. We can use them in conjunction with Automations or Workflows.
When do we choose automations or workflows?
Both workflows and automations will help you automate your processes, and they are both executed based on triggers and rules defined by you. We recommend using workflows for more complex processes because they will allow you to get more granular on every step of the process and they also provide a monitoring tool that allows you to review their execution in real-time.
Integrate Your Webform with FreeAgent
Step 1: Create the initial Webhook
In FreeAgent navigate to Admin Settings → Integrations → Webhooks and click on 'Add Webhook'.
For this initial step, we only need to fill out Name, and App (Contacts App) and then click 'save'. Adding a description is optional. Whenever we create a new webhook FreeAgent will automatically generate an URL that we will use to connect to our web form.
Once you've clicked 'save' select 'edit to open it back up. We can see the URL was automatically generated. Copy the URL as we'll need to use it in the next step.
Step 2: Connecting Your Webform
We're going to use WordPress in this example. WordPress is a common tool that uses Elementor as its plugin for web forms.
Once you have your webform built in Elementor, you can navigate to the left side on “Edit form” of Elementor → Settings → Add action → Select Webhook → Click on update at the bottom.
Note: You can also go back and edit your web form anytime by clicking on 'Edit with Elementor' underneath the form name in your 'Pages' section of WordPress Admin.
This action will enable a new section where we can add our FreeAgent CRM Webhook URL. Paste in the URL you copied from our FreeAgent Webhook in step 1.
Step 3: Create a Workflow
For this example, we will use FreeAgent Workflows to create a contact record in your FreeAgent account every time someone submits a web form.
FreeAgent workflows are done through a visual diagramming feature that is BPMN 2.0 compliant (Business Process Model and Notation). It's based on the Zeebe workflow engine. Zeebe is a workflow engine designed to meet the scalability requirements of high-performance applications running on cloud-native software architectures and to support workflows that span multiple microservices in low-latency, high-throughput scenarios.
You can navigate to the workflows of every app by going to Admin Settings → Apps Setup → Contacts (Select the app you will use) → Workflows, and click on 'Add Workflow'.
The name can be anything you want. However, it's helpful to use titles that reflect the intended functionality. For example, we will call this automation “Create Contact from Webform”. Make sure you have 'Contacts' selected as your target app.
On the field “Trigger” we will choose the option 'On Webhook'.
You can add conditions in cases where you want to specify that the workflow will run only under the rules you've set up.
we can start selecting the objects and connections on the left to create the visual diagram of our workflow.
We will begin with an initiating event called the Start Event. Designated by a circle with a thin border.
When we click on an object we can add the next object or connection. For our next step, we will select Add a script (represented by the </> symbols).
Double-click on the script to open the edit window. The script will be kept simple to run a quick test and verify how the information is being received. This can depend on the webform provider you’re using, their plugin, and the names of the fields.
Now that we have:
- Our webhook in FreeAgent
- Webhook URL is connected to WordPress
- Workflow to receive the information
- We’re ready to run a test.
Fill out your webform in WordPress with test information and we will go back to FreeAgent to review how the information was received.
Every time someone fills out your web form, the workflow will generate a “Workflow activity” activity in FreeAgent, where we can monitor if the workflow ran successfully and review the information that was received.
Navigate to the workflow activities of every app by going to Admin Settings → Automations → Workflow Activities. From here you can access a list view that shows every instance of a workflow being run. Click on the first record to review the details.
Note: make sure to click on the activity ID.
Double-click on the green script in the image and we will copy everything we see in the “Variable Value” of the first activity.
This contains all of the information that was received from the web form.
We recommend using a JSON Validator to get the information easier. One option for the JSON validator could be https://jsonlint.com/ where you can paste all of the information we received and click on “Validate JSON” to see everything organized.
In this example, we'll pull in the First Name, Last Name, and Email. We'll then copy the name as it is on the left side, keeping everything within the double quotes. For example: *FIRST NAME
Now that we know we’re receiving the information, we will go back to the script of our FreeAgent Workflow and we will replace the script code for the one below:
(function(workflow, context){
return {
firstName: workflow.entityInstance.body["* FIRST NAME"],
lastName: workflow.entityInstance.body["* Last NAME"],
emailAddress: workflow.entityInstance.body["* Email Adderess"],
};
}(workflow, context));
The information in blue will be the name of the field we have in FreeAgent. Where we want to map the information we received from the form which is represented in orange. In this example, we can see * Email Address has a typo but given that the information is received like this from WordPress we need to keep it to access that key of data.
In the section below “Output Parameters”, we will type the name of our FreeAgent fields, as we have them above with Camel Case type. For example, firstName.
* need more information from Mafer on the Output Parameters. Will need a screenshot to go with it.
Once you're finished click save and go back to the workflow at Admin Settings > Automations > Workflows.
Once you're back in your workflow click on the “+” sign, to “create” our next object. You can see that as soon as we select create, the previous step “Script” will be connected to the new object “Create”.
Double click the 'create' object and in this section, we will map the “input parameters”.
Once in the edit screen click on 'Add Parameter' under the 'Input Parameters' heading. Select the field that you would like to map. For example: 'First Name'
To get the value from the previous step “script”, we will type “script” and as soon as we add a “.” we will see the options from our previous step. In this example, we will select “firstName”.
We will click again on “Add Parameter” until we complete adding all of the fields we want to map and we will click in save.
Now that we have our information mapped, we can close our workflow. Click on the “create” object and then select the circle of the “end” object and click in save.
Once the workflow is ready, we only need to connect our FreeAgent webhook to our workflow. Navigate to Admin Settings → Integrations → Webhooks and click in the 3 little dots to edit our previous webhook.
Click on the field of Automation and we will select the name of our workflow from the dropdown and click in save.
That’s it. We’re ready to run a test. Fill out your web form and the contact should be created automatically in your FreeAgent account with the fields we mapped.
You can also navigate to Workflow Activities to review that the workflow ran correctly. It should show up in the 'completed' tab.
In a situation where there are errors, the status of the workflow will be “Error” and you can click on the Workflow ID to the left to get more details.