What is a webhook?

A webhook is a user-defined URL callback. It is a mechanism that enables apps to receive data updates in real time through a URL call. Webhooks can be incredibly helpful when you're working with data updates that need to be notified immediately such as payment transactions and ticket escalations.

Some important terms

Webhook
The mechanism of calling a URL when an event occurs. The data is sent over a specified URL on the web.

Webhook URL
The URL via which data is sent from one application to another when an event occurs.

Payload
The data received from the application via the webhook URL.

HTTP
Hyper Text Transfer Protocol. A data transmission standard that defines how servers and browsers send and interpret data.

Headers
Additional information transferred along with the HTTP request for purposes such as authorization and identification.

Webhook trigger

The webhook trigger in Zoho Flow lets you start your flow based on data updates received from an application that supports outgoing webhooks via a URL. This data can then be used in the actions in your flow. For example, you have a custom application used internally by your company to manage business transactions. If it supports configurable webhooks, you can set up a flow to start every time a specific type of data update is made in the application.

How does the webhook trigger work?

When you set up this trigger, a unique URL is generated by Zoho Flow. Use this to configure the settings in the third-party application or code to send data to Flow when a particular data update happens.

This trigger supports three types of data:

JSON

JavaScript Object Notation (JSON) is a lightweight data interchange format. It contains data as key-value pairs.

Example: {"name" : "Frank", "company" : "Zylker", "amount" : "400"}, 
Here "name" : "Frank" is the first key-value pair in which 'name' is the key and 'Frank' is the value.

Form data

A set of key-value pairs representing the form field names and their values, which can be used as a part of a HTTP request.

Example: name=Frank&company=Zylker&amount=400

Plain text

If you select the data as plain text, the incoming data will be rendered as it is sent via the URL.

Example: Zylker

Note: Select  Plain text for XML. You can further process it using a custom function.

name : Frank company : Zylker amount : 400

However, if you choose Plain text and the incoming data is name=Frank&company=Zylker&amount=400, Zoho Flow will interpret the data as:

data : name=Frank&company=Zylker&amount=400

In some cases, selecting the wrong data type may not trigger the flow as expected.

How to configure

1. In the My Flows section of Zoho Flow, click Create Flow or +.
2. Enter the flow name, and optionally a description.
3. Click Create.
4. Click Configure in the Webhook trigger box.
   
   
5. Your custom URL will be available. This URL is unique for each flow. Click Copy and paste it in your code or application.
6. Select the format (JSON, form data, or plain text) in which the application/code sends the data to Zoho Flow and click Next.
7. Click Test to check if everything is working correctly with sample data.
   
   
   
8. By default, the flow will trigger for each element. For example, suppose Zoho Flow receives the data as [{"name" : "Frank", "company" : "Zylker", "amount" : "400"}{"name" : "Tom", "company" : "Zylker", "amount" : "900"}] .
   
   Here, {"name" : "Frank", "company" : "Zylker", "amount" : "400"} is an element and {"name" : "Tom", "company" : "Zylker", "amount" : "900"} is another element. When this option is enabled, the flow will trigger twice. You can choose to uncheck the box.
9. If you only want the value of one particular key, you can specify it in the Extract part of payload field. For example, Zoho Flow receives the data as {"name" : "Frank", "company" : "Zylker", "amount" : "400"}, and you have entered name in this field. In this case, only the value for name will be extracted and all other values will be discarded. In the next steps of your flow, only the name will be available for you to use.
   
   
10. After configuring, click Done and add actions to your workflow.
    

Using advanced settings

Once you've tested the webook, you can access additional options to configure the trigger by clicking Advanced settings. 

Extract headers and use them in the next steps

This option will extract the headers in the payload received, and will provide them as variables under Webhook in the 'Insert variable' section in the flow builder. 

Tip: 

1. Headers hold additional information transferred along with the HTTP request for purposes such as authorization and identification.
   
2. Suppose you have configured the same webhook URL in multiple applications or servers. Use this option to determine which app has sent the data through the URL, i.e., data from which app has triggered the flow.
   

Extract part of the payload

This option will selectively extract the data from within the specified object present in the received payload. Only the value of the key mentioned will be extracted and all other values will be discarded. In the example given below, the payload contains "order", the parent object, and "sale"—the nested object. 

If you only need the data contained within sale to be available for use in your flow, you can enter order.sale in this option. Then the output will look like:

Trigger flow for each entry

With this option enabled, if the response payload has multiple objects, the flow will trigger, and execute for as many objects present in the payload.

For example, the following payload has 3 objects in it. The flow will trigger three times. The first execution will pass the values from the first object, the second execution with the second object, and so on.

Using variables from webhook trigger in conditions

While using Decision logic, it isn't possible to directly select a webhook trigger's output variable for the test condition. To use a specific variable from your webhook trigger, follow these steps:

1. Add a Set Variable logic following the webhook trigger to create a new variable.
   
2. Provide a name for the new variable.
   
3. Click on the field under Value, then click on the required webhook variable from the Insert Variable section on the right.
   
4. Click Done.
   
5. While configuring a test condition, select the new variable you've created from the dropdown.
   
   

Acknowledge receipt of webhook requests (Webhook verification)

You may occasionally wish to receive custom responses as acknowledgements for your webhook requests in order to ensure that only Zoho Flow is listening to the webhook requests from the application you've configured the webhook URL for. 

If you want Zoho Flow to send back custom acknowledgements upon receipt of incoming webhooks, you can enable it by checking the Enable webhook acknowledgement box under Advanced settings. You will then need to configure the custom message in either the response body or the header.

You can also configure it to send an acknowledgement just for the first webhook request or for all incoming webhook requests. 

Ensure that you configure at least one of the fields (headers or body) of the response for Zoho Flow to send acknowledgements successfully.

Common problems

1. The webhook trigger does not start when there is a data update.
   Make sure that you have chosen the right data type (JSON, form data, or plain text) while configuring the trigger. If the wrong option is selected, the flow may not be triggered.
2. Can the webhook trigger work with on-premise applications?
   If the on-premise application supports outgoing webhooks, the webhook trigger can use the data to start a flow.