Incoming Webhooks

Incoming Webhooks

Overview

Incoming Webhooks are the best way to post messages from different apps to your Zoho Connect Network, so you can stay updated on activities in your other applications without leaving Zoho Connect.

Getting started with Incoming Webhooks

Each Webhook has a unique URL to which you send a JSON payload in a defined format (from an another application). Later, this data gets posted in your Zoho Connect Group. This can help you track and stay notified about the activities in your other applications.

Key features of Incoming Webhooks


Feature
Description

 Configuration

Incoming Webhooks are available only at the Group level.

Flexibility 

Any application that can send HTTPS POST request can send messages using incoming webhooks.
Markdown
support
The messages in the payload supports basic HTML Markdown. Click here to learn more.
Attachments 
You can add up to 10 files to a Post. The size limit per file is 10 MB

Who can use the Incoming Webhook integration?

All members in the network can use this integration. However, the network admin can restrict/approve the integration.

 A member can create a maximum of 20 Webhooks. 

How to approve/restrict Incoming Webhook integration?

The network admin can approve/restrict the integration by following the steps below:
  1. Click the plug icon  from the vertical menu in the top-right part of the page.
            
  1. In the new page, click Manage from the left menu.
            
  1. Navigate to the Incoming Webhook and click the button in the right  to approve/restrict.
   
        

Once the network admin restricts the integration, members in the Network can neither configure a new Webhook nor use the existing one.

How to configure an Incoming Webhook?
  • Click the plug icon  from the vertical menu in the top-right part of the page.

            

  • Scroll through the list of Integrations and click Incoming Webhook.

  • Click Configure.

            

  • Select the Group, where you would like to post messages.

  • Enter a name for the Webhook, and upload an image. 

  • Click Save.

  • The new field that appears below the Custom Function will give you the URL for the Incoming Webhook. Messages from other applications will be sent to this URL, and the URL is also specific to the Group that you have selected.

            

  • Copy the Webhook URL to the clipboard and save it. 

How to post a status using an Incoming Webhook?


Now that the URL for the Incoming Webhook has been saved, you'll need to make an HTTP POST request in the format mentioned below:
  1. POST https://connect.zoho.com/webhook/v1/incoming/intranet/499400157703126zapikey=XXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

    Content-type: application/x-www-form-urlencoded

     payload-{"message":"<b>Service Request</b> <br><br> Your service request has been approved.Kindly contact your administrator to proceed further"}

Once the request is made, a message is posted in the configured Group.

            

Ensure that the request is in "application/x-www-form-urlencoded" format. If not, an error message will be generated.

Not just this, you can do a lot more using an Incoming Webhook. Click here to know more.

Response codes for a Post made using an Incoming Webhook

Once you have posted a Message using an Incoming Webhook, you'll receive either one of the following messages as a response.

If the message is successfully posted, you'll receive the following response:

      status code: HTTP 200
  1. {"status":"success","id":"unique id of post/comment created"}

On failure, you'll receive the following response:
      
      Status code: HTTP 400
  1. {"status":"failure","errorCode": "EXTRA_KEY_FOUND","reason":"Extra key found in the JSON parameter payload"}

Custom Function in Incoming Webhooks

Every app has its format to send and receive messages. If your request does not fit into any of the pre-defined formats, you can write a Custom Function. The custom function will structure your unformatted requests into the Webhook format. If you've written your custom function, then the Map return by the Custom function will be considered as the input for the Webhook process.

To write a Custom Function follow the steps below:
  • Click integrations from the vertical menu in the top-right part of the page.

  • Scroll through the list of Integrations and click Incoming Webhook.

  • Click Configure to create a new Incoming Webhook, or open an existing one.

  • Navigate to Custom Function, click  Write function.

            

  • In the pop-out editor, write your code.

  • Once done, close the editor and click Save. 

The custom function requires the authentication of your Network admin to be accessed by all other members in your Network. 


The following parameters should be passed to the custom function during runtime:
  1. params - Map (Key Value pair of all the parameters sent with the request)
  2. headers - Map (Key Value pair of all the headers of the request)
  3. body - String (content written in the body of the request)
  4. network - Map(Key Value pair of details about the current network)

Network detail example:
  1. { "createdBy":{"name":"mark","emailId":"mark@zillum.com", "id":"142283" }, "domian":"zillum.com", "name":"zillum Network", "id":"22000000002002", "type":"2", // 2 for intranet , 4 for extranet "plan":"2",//0 for free, 1 for trial and 2 for enterprise "url":"https://connect.zoho.com/portal/intranet" }

Response codes for a Custom Function

Function executed and post added successfully:
  1. { "customFunctionResponse": {"message": {"userMessage": []},"output": {"payload":{"message": "Testing Content","linkUrl": "https://connect.zoho.com/portal/intranet"}},"status": "success"},
    "status": "success",
    "id": "3000000577088" }
Function executed successfully but failed while adding post:
  1. { "customFunctionResponse": {"message": {"userMessage": []},"output": {"payload":{"message": "Testing Content","value":"Content for test"},"streamId":"3000000577088","messageType":"comment"},"status": "success"},

    "status": "failure",
    "errorCode": "1044",
    "reason": "Extra key found in the JSON value" }
Function execution failed:
  1. { "customFunctionResponse": {"status": "failure"},

    "status": "failure",
    "errorCode": "1045",
    "reason": "Unable to execute custom function" }

How to protect your Webhook URL?


Anyone who has the URL will be able to send messages to it and post in your Group. So keep it safe and don’t share it online. In case the URL is used without proper authorization, you can re-generate it anytime. 


To re-generate the Webhook URL do the steps below: 
  • Click Integrations from the vertical menu in the top-right part of the page.

  • Navigate to Incoming Webhook.

  • Open the required Webhook, navigate to Webhook URL

  • Click Re-generate, seen in the bottom-right of the URL box.

                        




Click here to know more about the advanced message formatting options in Incoming Webhook.







    Zoho DataPrep Personalized Demo

    If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

    Zoho CRM Training

      Create, share, and deliver

      beautiful slides from anywhere.

      Get Started Now





              Zoho CRM Training Programs

              Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

              Zoho CRM Training

                Zoho SalesIQ Resources



                    Zoho TeamInbox Resources




                              Zoho DataPrep Resources

                                Zoho DataPrep Demo

                                Get a personalized demo or POC

                                REGISTER NOW


                                  Design. Discuss. Deliver.

                                  Create visually engaging stories with Zoho Show.

                                  Get Started Now











                                                        • Related Articles

                                                        • Message formats in Incoming Webhooks

                                                          Overview This document will help you with a few basic message formatting options in Incoming Webhooks, required parameters, the input data, and how to implement it. Click here to learn about the basics of Incoming Webhooks. What are the parameters ...
                                                        • Advanced message formatting options in Incoming Webhooks

                                                          Overview You can keep your Posts simple as a single line of text, or present the information in a distinguished manner with the help of the advanced formatting options.  In the advanced formatting option, the JSON payload that you send to the Webhook ...

                                                        Resources

                                                        Videos

                                                        Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                        eBooks

                                                        Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                        Webinars

                                                        Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                        CRM Tips

                                                        Make the most of Zoho CRM with these useful tips.



                                                          Zoho Show Resources