Applicable plans
Sprout Blossom Garden EstateForest


What is Webhook?

Webhook is used to send HTTP requests to a third party app or web service every time an event(when conditions are met) occurs in Freshsales.

This URL of the app or web service that’s hit by the API request is called a callback URL.

For eg: When a deal is won, you can send a request to generate an invoice from a third party app using a webhook request. 


Who could possibly configure this? 

  • Admin of a Freshsales account

  • Developers with REST API skills



You may configure HTTP URLs and associate them in workflow rules to automate the entire process.

Let’s see how to configure one such case.


Scenario: When a deal is won in Freshsales, an external invoice generator automatically generates an invoice via a webhooks request.


How to setup a Webhook request in Freshsales? (Learn more)


Workflow:



  1. Log in as an Admin > Admin Settings > Workflows > New Workflow.

  2. Add a 

           Name: Generate invoice when deal is won using Webhooks.

           Description: For every deal won, automatically generate an invoice from Invoice 

                                 generator app using webhooks.

  1. Choose the Record type: Deal.

  1. Configure your Workflow’s, 

           Execution trigger: Once, when it’s created or updated

           Conditions: Deal Property > Deal stage > is in > {Pipeline}:Won

  1. Now choose an action from the drop-down.

           Action: Trigger webhooks

       6.  In the overlay that comes up, 

                

       a:  Choose the Request type as POST. (We are creating an object(invoice)).


            The request types available in Freshsales are:


   


    Each 3rd party app uses the request type in a different way, but most applications follow standard methods.


Request type

Fields 

GET or DELETE

  • The callback URL (required)

  • Authentication parameter (optional)

  • Custom headers (optional)

POST, PUT or PATCH

  • The callback URL (required)

  • Authentication parameter (optional)

  • Custom headers (optional)

  • Encoding (required)

  • Content type (required)

  • Content (required)

    

b:  Enter the invoice generator’s URL, say: https://invoice-generator.com/#/1

      If you want to add the deal’s id as a placeholder please use the Advanced 

      content option.


c:  If the third party application’s URL that is going to be hit requires authentication, then 

     check the Requires Authentication option. You can authenticate either with,

  • Username and password

  • Your account(third party app’s) API key


d:  Add custom headers to pass along some additional 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:

  • 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.

  • A header with more than one value should be separated by delimiters (don’t use comma or colon). 

  • To add a second header, enter the custom header and value pair in the next line.


e:  Let’s select JSON as the encoding format and choose the Simple content(Deal  

     details) that needs to be sent as a part of the webhook request.

     And let us choose, Deal Value, Closed date, Created at, Product & Name(Sales 

     Account) as the fields to be sent as a part of the HTTP request.


Note: 

  • The other encoding formats available are XML and XML(extended).

  • To customize the content that is being sent, select Advanced.

     

f:   Now Test the URL. Your, 

  • request_sent section would have the following code

  • response_ received section would imply the status of the request, as in if it was received successfully by the app or was it a failure.

     

     

Note: To know more about decoding the error, check the below section on How do I test if my Webhooks 

           request is working?


g:  Save the settings.

7. Either Save & Start the workflow immediately or just Save it for now and activate it later.


How do I test if my Webhooks request is working?

You can test a sample case using the Test URL option. The callback status code comes up as a toaster message.


If the callback status codes are between 200 and 299, the callback is a success. 

Status codes other than 2xx indicate failure of the callback.


Note:  When your callback fails, 

  • You will receive an email mentioning the Callback URL that failed.

  • We will retry sending the request for an hour from then.

  • If it still fails, we’ll retry for the next 2 days before permanently terminating the Webhook request.