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:

  1. Request Type

  2. Callback URL

  3. Encoding type

  4. Content

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

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

     

  2. Encoding Type: Choose between JSON, XML, or X-FORM-ENCODED 

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

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



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

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


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.

Error CodeType of error codeWhat it means

301

Moved permanently

The requested resource has permanently moved to a different URL.

302

Moved temporarily

The requested resource has temporarily moved to a different URL.

400

Bad request

The request you sent is invalid (syntax could have invalid parameters or size might be too large).

401

Unauthorized

You don't have permission to access the resource. Authentication has failed/not been provided.

403

Forbidden

Your request is correct, but you're not authorized to perform the requested operation.

404

Not found

The requested resource is not available at the moment.

405

Method not allowed

Your request method is not supported for the requested resource.

409

Conflict

Your request can't be processed because there's a conflict with another request at the server's end.

422

Unprocessable entity

Your request is correctly framed, but the server can't process the contained instructions.

429

Too many requests

You've sent quite a lot of requests recently.

500

Internal server error

The server encountered an internal error or misconfiguration.

502

Bad gateway

The server is a gateway/proxy and has received an invalid response from the upstream server.



Read Timeout errorWhen a webhook is triggered from Freshsales, it expects a response within 6 seconds. In case it doesn't get a response, this error is thrown.
The API might be successful post that.
Note: 

The error codes added above are the most commonly reported. This is not an exhaustive list. Errors specific to 3rd party applications will require inspection of their respective developer documentation to identify reasons for webhook failure.


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.