Webhooks are event-based triggers that send HTTP requests to a third-party app or website when defined conditions are met.
In simple words, webhooks are automation that can make changes to a webpage or product when conditions are met.
In Freshsales, you can use webhooks to send data to a third-party website or even create new records inside the CRM based on the trigger conditions.
For example, you can set up a webhook triggered based on conditions to send an invoice automatically when a deal is signed.
We can implement this workflow using a 3rd party invoice generator tool.
Let's try and use the free invoice generator tool offered by Invoiced. Invoice Generator provides an invoice template that enables users to create and send professional invoices. It also supports API calls. This allows us to use it as a part of our Webhooks use case.
- Setting up webhooks requires a basic understanding of REST APIs. If you are not familiar with coding, it is recommended that you enlist the help of developers to set up webhooks.
- Invoice Generator by Invoiced has been chosen in this use case as it allows registered users to generate invoices through their APIs for free. Please refer to Invoiced’s API documentation to understand the tool better.
Now let’s understand how to configure a webhook based on our example— create a new deal based on contact conditions. Webhooks are triggered as a part of Actions in Workflow.
To learn how to configure workflow triggers and conditions, refer to this article.
What constitutes a webhook?
Setting up a webhook constitutes configuring the following:
Freshsales APIs support Representational State Transfer (REST). This means you can set up APIs that perform 'RESTful' operations—reading, modifying, adding, or deleting data from the CRM. You can choose one of the following request types while configuring your webhook:
Create an object
Fetch one or more objects
Update an object
Remove an object
Note: Each 3rd party app uses the request type in a different way, but most applications follow standard methods.
In the case of our example, we are choosing POST as we are posting an API request to Freshsales to create a deal.
Callback URL: The URL of the app or web service that’s hit by the API request is called a callback URL. In the case of our example, we are trying to create a deal. So, we can use the deal page URL for creating a deal.
Invoice Generator Callback URL for generating an invoice:
Authentication (Optional): If the callback URL requires authentication to go through, you can add either the username and password or the API key.
In the case of our example, Invoiced does not require an Authentication through API or Username-Password to run
Click Add custom headers to include information with the content such as security details, API version details, and so on. A custom header has to be entered as a header-value pair in the following format: X-Sample-CustomHeader1: VALUE.
1. The trigger will not be executed when a header is given with spaces in between, like X-Sample Custom Header1: VALUE. Although, if space is entered at the end of the header(X-Sample-CustomHeader1 : VALUE), it will be skipped.
2. A header with more than one value should be separated by delimiters (don’t use comma or colon).
3. To add a second header, enter the custom header and value pair in the next line.
Encoding Type: Choose between JSON, XML, or X-FORM-ENCODED
Content: You can send two types of content as a part of the webhooks— Fields or Endpoints. Choose the Simple or Advanced content (Deal details) that need to be sent as a part of the webhook request.
Simple: Select fields from the record type of choice to send it as a part of the webhook.
Advanced: You can send an endpoint to the callback URL. Endpoints refer to a piece of code/information that is delivered at the callback URL. Create endpoints with placeholder by using relevant API. Refer to Freshsales developer documentation to find API for different actions.
In the case of our example, you can opt to create a new invoice for the deal using the Deal value and Sales owner.
GET or DELETE
POST, PUT or PATCH
When the webhook is triggered, an invoice will be sent to the Sales account for whom the new deal has been created in Freshsales.
Testing the webhook
After configuring the webhook, test the webhook by clicking button. If your configuration is right, you will receive a Success message. If configured incorrectly, you are likely to be presented with error codes. Refer to this documentation to understand the error codes and fix them accordingly.
1. You will receive an email mentioning the Callback URL that failed.
2. Your application will retry sending the request for an hour from then.
3. On continued failure, the web application will retry sending the request for the next 2 days before permanently terminating the Webhook request.