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.
Workflow:
Note:
- 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:
Request Type
Callback URL
Encoding type
Content
Request Type
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:
REQUEST TYPE | PURPOSE |
POST | Create an object |
GET | Fetch one or more objects |
PUT/PATCH | Update an object |
DELETE | 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:
https://invoice-generator.com
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.
Note:
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.
In simple type, the webhook sends the data in a predefined format, which might not match the format of the API endpoint to which you would like to send the data.
Hence it is always better to go for the Advanced option.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.
REQUEST TYPE | FIELDS |
GET or DELETE |
|
POST, PUT or PATCH |
|
Placeholders:
- When creating a webhook for the Contacts workflow, the placeholders available for the fields are only from Contact and the linked Primary Account.
- When creating a webhook for Accounts workflow, only Account fields are available.
- When creating a webhook for the Deals workflow, the placeholders available are for Deal and the related account.
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 thebutton. 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.
Generally, if you are testing webhooks, and you are using placeholders, it sends only sample data. That might work while triggering API to third-party endpoints, but the same might throw a 404 or 400 error on testing based on the type of placeholders passed.
- When using {{contact.id}}/{{sales_account.id}}/{{deal.id}} placeholder, the test will only send test data as "12345", which will not be the right ID, hence giving "404 Not Found error".
- requireWhen using placeholders for date fields/tags etc which requires data to be passed via API in a certain format, testing the webhook might throw a "400 Bad Request error".
It is okay to proceed with testing the workflow rather than just the webhook so that actual data are passed through placeholders in order to confirm if the Webhook is correctly set up.
Note:
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.