受信Webhook

受信Webhook

概要

受信Webhookを利用すると、別のアプリからZoho Connectのグループにメッセージを投稿できます。Zoho Connectのグループから別のアプリの最新情報を確認することが可能になります。

受信Webhookの利用開始にあたって

Webhookを設定すると、データ送信用のURLが設定ごとに発行されます。このURLに対してデータ（JSON形式）を送信することで、Zoho Connectにメッセージを投稿できます。他のアプリからこのURLに対してデータを送信すると、設定内容に応じてZoho Connectのグループにメッセージが投稿されます。受信Webhookによって、Zoho Connectの画面上にさまざまなアプリの情報を集約できます。一方、受信WebhookのURLを利用すると誰でもグループに投稿が行えるため、受信WebhookのURLの管理には注意が必要です。

受信Webhookの主な機能

機能
説明
 設定

受信Webhookは、Zoho Connectのグループでのみ利用可能です（ネットワークの掲示板や自分のフィードでは利用できません）。

対応アプリ 
HTTPSを通じてPOSTリクエストを送信できるアプリであれば、受信Webhookを通じてZoho Connectにメッセージを送信可能です。
マークダウン（書式設定の記法）
対応
データのメッセージは、基本的なHTMLのマークダウン（書式設定の記法）に対応しています。マークダウンの詳細については、こちらをご参照ください。
添付ファイル 
1件の投稿に10件までファイルを追加できます。ファイルごとのサイズの上限は、10MBです。

受信Webhookによる連携機能を利用できるユーザー

ネットワークのすべてのメンバーが、受信Webhookによる連携機能を利用できます。ただし、ネットワーク管理者は、ネットワーク全体に対して連携機能を制限／許可できます。

 メンバーが作成できるWebhookの上限は、20件です。 

管理者が受信Webhookの連携を許可／制限する方法

ネットワーク管理者は、以下の手順によって、受信Webhookの連携を許可／制限できます。
  1. ページの右側のメニューの上部に表示されているコンセントのアイコン（［連携］）をクリックします。

       

  1. 表示されたページで左側のメニューから［管理］をクリックします。
            

  1. 連携の一覧から［受信Webhook］に移動し、［受信Webhook］の右に表示されている［承認する］／［制限する］をクリックします。
   
        

ネットワーク管理者が連携を制限すると、ネットワークのメンバーは、新しいWebhookを設定したり、既存のWebhookを利用したりできなくなります。


受信Webhookの設定方法

  • ページの右側のメニューの上部に表示されているコンセントのアイコン（［連携］）をクリックします。

            

  • 連携機能の一覧のページで、［受信Webhook］の項目まで画面をスクロールします。

  • ［設定する］をクリックします。

            

  • メッセージの投稿先のグループを選択します。

  • Webhook名を入力し、必要に応じて、アイコン用の画像をアップロードします。 

  • ［保存する］をクリックします。

  • ［カスタム関数］の下に追加された［WebhookのURL］の項目で、受信Webhook用のURLが確認できます。別のアプリからのメッセージは、このURLに対して送信されます。このURLは、受信Webhookの設定において選択したグループに専用のアドレスです。

          

  • WebhookのURLをクリップボードにコピーして、POSTリクエストの送信先として利用できるよう保管しておきます。
     


受信Webhookを利用してメッセージを投稿する方法


受信WebhookのURLが保存できたら、以下の形式でPOSTリクエストを作成します。

  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"}

POSTリクエストが送信されると、メッセージの内容が、設定したグループに投稿されます。

            

リクエストは、「application/x-www-form-urlencoded」の形式である必要があります。形式に誤りがある場合は、エラーメッセージが生成されます。

この他にも、受信Webhookを用いてさまざまなメッセージの投稿が可能です。詳細は、こちらをご参照ください。


受信Webhookにより作成されたPOSTリクエストに対する応答（レスポンス）の番号

受信Webhookを利用してメッセージを投稿すると、応答（レスポンス）として以下のメッセージのいずれかが表示されます。

メッセージが問題なく投稿された場合の応答（レスポンス）は、以下のとおりです。

      ステータス番号：HTTP 200
  1. {"status":"success","id":"unique id of post/comment created"}

失敗の場合の応答（レスポンス）は、以下のとおりです。
      
      ステータス番号：HTTP 400
  1. {"status":"failure","errorCode": "EXTRA_KEY_FOUND","reason":"Extra key found in the JSON parameter payload"}

受信Webhookにおけるカスタム関数

Zoho Connectとの連携対象のアプリの側では、アプリから送信できるデータの形式が決まっていて変更できないことがあります。もし対象のアプリから送信されるデータの形式がZoho Connectで標準的に受信可能な形式に合わない場合、そのままだとZoho Connectにメッセージを投稿することはできません。このような場合、カスタム関数を作成することで対応できます。カスタム関数を利用すると、受信したデータの内容を、Zoho Connectで必要な形式に変換することが可能です。カスタム関数を作成した場合、関数内で処理した結果をMap形式の値として出力する必要があります。その値をWebhookの入力値として処理することで、メッセージを投稿することが可能です。

カスタム関数の作成方法は、以下のとおりです。

  • ページの右側のメニューの上部に表示されているコンセントのアイコン（［連携］）をクリックします。

  • 連携機能の一覧のページで、［受信Webhook］の項目まで画面をスクロールします。

  • ［設定する］をクリックして新しいWebhookを設定するか、既存の設定を開きます。

  • カスタム関数の項目に移動して、［関数を作成する］をクリックします。

          

  • 表示された画面でコードを入力します。

  • コードの入力が完了したら、編集画面を閉じて、［保存する］をクリックします。 

ネットワーク内のすべてのメンバーがカスタム関数にアクセスするには、ネットワーク管理者による認証が必要です。 


カスタム関数の実行時に渡されるパラメーターは、以下のとおりです。
  1. params - Map（リクエストで送信されるすべてのパラメーターのキーと値のペア）
  2. headers - Map（リクエストのすべてのヘッダーのキーと値のペア）
  3. body - テキスト／文字列（リクエストの本文に記載される内容）
  4. network - Map（現在のネットワークの詳細についてのキーと値のペア）

ネットワークの詳細の例：
  1. { "createdBy":{"name":"mark","emailId":"mark@zillum.com", "id":"142283" }, "domain":"zillum.com", "name":"zillum Network", "id":"22000000002002", "type":"2", //内部ネットワークの場合は2、外部ネットワークの場合は4を記入します "plan":"2",//無料プランは0、試用版は1、エンタープライズプランは2を記入します "url":"https://connect.zoho.com/portal/intranet" }


カスタム関数用の応答（レスポンス）のステータス番号

関数の実行と投稿の追加が問題なく完了した場合：
  1. { "customFunctionResponse": {"message": {"userMessage": []},"output": {"payload":{"message": "Testing Content","linkUrl": "https://connect.zoho.com/portal/intranet"}},"status": "success"},
    "status": "success",
    "id": "3000000577088" }
関数の実行が問題なく完了し、投稿の追加が失敗した場合：

  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" }
関数の実行に失敗した場合：

  1. { "customFunctionResponse": {"status": "failure"},
    "status": "failure",
    "errorCode": "1045",
    "reason": "Unable to execute custom function" }


WebhookのURLを保護する方法


WebhookのURLを利用すると、誰でもグループにメッセージを送信、投稿できます。そのため、WebhookのURLは、安全に保管し、不必要に共有しないことが大切です。また、URLの不正利用の防止などの理由で現在のURLを変更したい場合などは、URLを生成しなおすことができます。 


WebhookのURLをもう一度生成する手順は、以下のとおりです。 

  • ページの右側のメニューの上部に表示されているコンセントのアイコン（［連携］）をクリックします。

  • ［受信Webhook］の項目まで移動します。

  • URLをもう一度生成したいWebhookを開き、［WebhookのURL］の項目まで画面をスクロールします。 

  • URLの右下に表示されている［もう一度生成する］をクリックします。

                        




受信Webhookのより高度なメッセージ形式については、こちらをご参照ください。