Incoming Webhooks

Incoming Webhooks

Feature Availability

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.







    Access your files securely from anywhere

      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
        Redefine the way you work
        with Zoho Workplace

          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 Sign now offers specialized one-on-one training for both administrators and developers.

              BOOK A SESSION









                                            You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.




                                                Manage your brands on social media

                                                  Zoho Desk Resources

                                                  • Desk Community Learning Series


                                                  • Digest


                                                  • Functions


                                                  • Meetups


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner


                                                  • Word of the Day


                                                    Zoho Marketing Automation

                                                      Zoho Sheet Resources

                                                       

                                                          Zoho Forms Resources


                                                            Secure your business
                                                            communication with Zoho Mail


                                                            Mail on the move with
                                                            Zoho Mail mobile application

                                                              Stay on top of your schedule
                                                              at all times


                                                              Carry your calendar with you
                                                              Anytime, anywhere




                                                                    Zoho Sign Resources

                                                                      Sign, Paperless!

                                                                      Sign and send business documents on the go!

                                                                      Get Started Now




                                                                              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 ...
                                                                                                              • An example for Function API

                                                                                                                Let us consider an example in which a new task is created in Zoho Connect whenever a ticket is added in Zoho Desk. This is implemented using an Outgoing Webhook in Zoho Desk that will make a POST request to an API endpoint in Zoho Connect. But Desk's ...
                                                                                                              • Working with Custom Apps

                                                                                                                Who can create a Custom App? Depending on the permissions set by the admin, members might or may not be able to create a Custom App in the Group or Company Wall. How do I create a Custom App? Click Custom Apps from the main menu on the left. Click ...
                                                                                                              • Prerequisites for adding comments, posts, and tasks through email

                                                                                                                Overview Zoho Connect enables you to add comments, posts, and tasks in your network from your email. If your organization uses a custom email domain that contains your business' domain (example: user@zylker.com), the organization admin must configure ...
                                                                                                                Wherever you are is as good as
                                                                                                                your workplace

                                                                                                                  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