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.