Understand incoming webhooks  

Incoming Webhooks let you send updates from another application into Zoho CommunitySpaces by posting a JSON payload to a unique webhook URL. In the referenced configuration, webhooks are available at the space level, support HTTPS POST requests, accept basic HTML markdown in the message, allow up to 10 files per post with a 10 MB limit for each file.

Check the table below for your plan’s webhook creation and execution limits.

Configure an incoming webhook  

1. Click the gear icon in the right menu.
   
   
   
   

2. Click Incoming Webhook under Automation.
   
   
   
   

3. Click Configure.
   
   
   
   

4. Select the Space or Board where you want the webhook to post messages.
   
   
   
   

5. Enter a name in the Name field and upload an image if required.

6. Optionally, add a description, and click Save.
   
   
   

After you save the webhook, the system generates a unique webhook URL under the Webhook URL section. Copy that URL and store it securely, because other applications will use it to post into the selected space.  

Post a simple message  

Incoming Webhooks must use application/x-www-form-urlencoded (or) multipart/form-data. The example below follows the request structure shown in the source article, with the domain adapted to CommunitySpaces.

 curl --request POST \
  --url 'url got from the configuration' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'payload={"message":"<b>Service Request</b><br><br>Your community request has been approved. Kindly contact your host to proceed further."}'

When the request is valid, the message is posted in the configured space.  

Understand response codes  

When a webhook post succeeds, the service returns HTTP 200 with a success status and the created item ID. When the request fails validation, it returns HTTP 400 with a failure status, an error code, and a reason.  

Success response:

{"status":"success","id":"<post_or_comment_id>"}
Failure response:
{"status":"failure","errorCode":"EXTRA_KEY_FOUND","reason":"Extra key found in the JSON parameter payload"}

Use a custom function  

Use a custom function when the source application cannot send data in one of the predefined webhook formats. The function transforms the incoming request into the webhook format, and the map returned by the function becomes the webhook input. The custom function must be authenticated by superhost and host. At runtime, it receives four inputs: params, headers, body, and community.  

To add a custom function:

1. Click the gear icon in the right menu.
   
   
   
   

2. Click Incoming Webhook under Automation.
   
   
   
   

3. In the page, create a new webhook or open an existing one.

4. Go to Handlers in the webhook configuration page and click expand.
   
   
   
   

5. Click Write function.
   
   
   
   

6. Enter your code in the editor.
   
   
   
   

7. Close the editor and click Save.  

A custom function can return three broad outcomes: full success, function success but post failure, or function execution failure.  

Protect and regenerate the webhook URL  

Anyone who has the webhook URL can post to it, so do not share it publicly. If you think the URL has been exposed, regenerate it immediately.  

1. Click the gear icon in the right menu.
   
   
   
   

2. Click Incoming Webhook under Automation.
   
   
   
   

3. Open the webhook you want to update and click Edit Configuration in the pop-up.
   
   
   
   

4. Go to the Webhook URL section.
   
   
   
   

5. Click Regenerate in the bottom-right corner of the URL box.

 Viewing Logs for Incoming Webhooks 

As a superhost and host, you can view incoming webhook logs to track requests and check whether they ran successfully. If a request fails, review its log details to identify the issue and troubleshoot it.

Related articles:

1. Sending basic message formats with incoming webhooks in Zoho CommunitySpaces  
2. Using advanced message formatting with incoming webhooks in Zoho CommunitySpaces

For any queries or feedback, reach out to us at support@zohocommunityspaces.com.