Webhook

Webhook

Webhooks allows you to integrate Zoho Mail with other external applications. A webhook is used to trigger an action in one application using real-time events from an external application. Webhooks are of two types - Incoming webhooks and Outgoing webhooks. Incoming webhooks are used to trigger an action inside Zoho Mail using real-time events from third-party applications. With outgoing webhooks, your incoming emails can be configured to trigger actions in external applications. 

How does it work?

In order to set up an integration between Zoho Mail and any third-party application, you will have to configure an incoming webhook in one application and an outgoing webhook in the other application. For example, if you wish to post events from an external application to your Streams group, the following steps should be carried out.

  1. Configure an incoming webhook in Zoho Mail.
  2. Obtain the Webhook URL generated while creating the incoming webhook.
  3. Configure an outgoing webhook in the third-party application using the webhook URL obtained.

If you wish to trigger an event in the external application when you receive emails, you need to configure the outgoing webhook in Zoho Mail and the incoming webhook in the third-party application. 

Incoming webhooks

An incoming webhook lets you post to the URL of your choice when a specified event occurs in a third-party application. You can configure the incoming webhook to post a message, note or task in your Streams group using the information received from the external application. 

Configuring Incoming webhook

  1. Login to Zoho Mail
  2. Navigate to Settings  >> Integration >> Developer Space 
  3. Select Incoming Webhooks under Configure section in the left menu.
  4. Click on Add new configuration
    Configuring incoming webhook
  5. Select the post format
    Selecting post format
    • Mail - Webhook update will be sent to your inbox as an email. 
    • Post/ Notes/ Task - Webhook update will be posted in the preferred Streams group as a post/ note/ task
  6. If you have chosen Mail in the previous step, skip this step. If you have chosen post/ notes/ task, enter the following details in the configuration page:
    Username and group settings to make the required post
    • ​​Custom Username - This name will be used to post in Streams
    • Group - The group where the updates will be posted
  7. Then, click on Write Function under Custom Function if you wish to modify the data in the post request to suit the webhook format as per your needs. Once you create the custom function, click on Select custom function to select the function.
    Selecting custom function
    Note:
    You can establish connections between any third-party application of your choice using DRE Connectors.
  8. Click Generate URL and copy the URL created. 
    Generate URL for your post

The URL that has been generated is used while configuring an outgoing webhook in the third-party application of your choice. 

Note:

Incoming webhook can be configured for a Streams group only by the moderators or owner of the group.

Points to remember

  • If you wish the Streams post to include an @mention, include the following in the message body:
    • To @mention a group member, include @emailID in the message. Example: To @mention Rebecca, @rebecca@zylker.com
    • To @mention a group, include @group in the message. The group configured for the webhook will automatically be tagged. 
  • The webhook URL should not be disclosed to unauthorized persons. If exposed, they will be able to post updates to your Streams group. 
  • If you re-generate the webhook URL, you will need to replace the old URL with the new URL in all the places it has been used. 

Outgoing webhooks

An outgoing webhook allows you to configure your emails to trigger events in third-party applications. You can post the details of the emails you receive to external applications. The filters options in the configuration allow you to select which emails you want to act as triggers for the event. 

Configuring Outgoing webhook

  1. Login to Zoho Mail
  2. Navigate to Settings  >> Integration >> Developer Space 
  3. Select Outgoing Webhooks under the Configure section in the left menu.
  4. Click on Add new configuration
  5. Enter the following details in the configuration page:
    Enter URL in the outgoing webhook
    • ​​Custom Username - The name given to the webhook configuration
    • Webhook URL - URL obtained from the incoming webhook configuration in the third-party app. Updates triggered from Zoho Mail will be posted to this URL.
    • Mail condition type - The emails that satisfy these criteria will trigger events in the third-party application.
  6. Click on Write Function under Custom Function if you wish to modify the data in the post request to suit the webhook format as per your needs. Once you create the custom function, click on Select custom function to select the function.
    Select Custom Function for your outgoing webhook
  7. Click Save.

Note:

  • If the webhook URL used in the configuration is unresponsive for an extended period, the outgoing webhook will automatically be disabled.
  • When you save an outgoing webhook configuration for the first time, a POST request is initiated. The configuration will be saved only if a 200 response is received for the POST request. 

WEBHOOK RESPONSE SAMPLE: 

{
     "summary": "Hi Rebecca, I have shared the slide deck for our product pitch meeting on Friday. Please take a look and do let me know if you have any suggestions. Regards, Paula",
     "sentDateInGMT": 1560866021000,
     "subject": "Marketing - Product pitch",
     "messageId": 1560840837125110000,
     "toAddress": "\"Rebecca A\"<rebecca@zylker.com>",
     "folderId": 3881227000000013000,
     "zuid": 647772765,
     "ccAddress": "",
     "size": 55503,
     "sender": "Paula",
     "receivedTime": 1560840837126,
     "fromAddress": "paula@zylker.com",
     "html": "<meta /><div><div style=\"font-family:&quot;Trebuchet ms&quot;, Arial, Helvetica, sans-serif;font-size:12pt;\"><div>Hi Rebecca,<br /></div><div><br /></div><div>I have shared the slide deck for our product pitch meeting on Friday. Please take a look and do let me know if you have any suggestions.<br /></div><div id=\"\"><div><img src=\"/zm/ImageDisplay?f=1.png&amp;mode=inline&amp;cid=0.28869215260.3894179596053002321.16b695cdb49__inline__img__src&amp;\" width=\"145\" height=\"145\" style=\"float:left;\" /><br /></div><div><br /></div><div><br /></div><div>Regards,<br /></div><div>Paula<br /><br /></div></div><br /><br /><div style=\"clear:both;\"></div></div><br /></div>",
      "IntegIdList": "34000000580271,"
}

Securing Webhooks 

Securing your webhooks is recommended as it helps you determine if the requests have actually originated from Zoho Mail. To enable you to verify the webhooks, Zoho Mail adds a signature to all its webhook requests. This adds an extra layer of security to your webhooks. 

Validating Webhook requests

Each webhook request contains a signature for verification purpose. The key that is used to sign the message is the x-hook-secret. This secret is obtained only from the header of the very first request of the webhook. The x-hook-signature is found in the HTTP header of all requests. The header is a base 64 digest of an HMAC SHA256 hash. The hashed content should be the binary representation of the full request body. 

In order to verify the signature, you will be required to generate a signature of your own using the x-hook-secret. You can then compare the generated signature with the signature in the request header to check the authenticity of the request. 

The sample code for checking the validity of a request is given below:

JAVA: 

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.servlet.http.HttpServletRequest;


//method to validate webhook request
boolean verifyWebhookRequest(String secret, String payload, HttpServletRequest request) throws Exception
{
          Mac mac = Mac.getInstance("HmacSHA2256");
          SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
          mac.init(secretKey);
          String signature = Base64.encodeBase64String(mac.doFinal(payload.getBytes()));
          return signature.equals(request.getHeader("X-Hook-Signature"));
}
 

JAVA SCRIPT:

function VerifyWebhookRequest(request, secret) 
{
//secret is x-hook-secret while registering webhook to URL
          var crypto = require('crypto');
          var headerHash = request.headers['x-hook-signature'];
          var createdHash = crypto.createHmac('sha256' , secret).update(request.body).digest('base64');  
          return headerHash = = = createdHash;
}

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohomail.com