受信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のより高度なメッセージ形式については、こちらをご参照ください。







    Zoho CRM 管理者向けトレーニング

    「導入したばかりで基本操作や設定に不安がある」、「短期間で集中的に運用開始できる状態にしたい」、「運用を開始しているが再度学び直したい」 といった課題を抱えられているユーザーさまに向けた少人数制のオンライントレーニングです。

    日々の営業活動を効率的に管理し、導入効果を高めるための方法を学びましょう。

    Zoho CRM Training










                              • Related Articles

                              • 受信Webhookのメッセージ形式

                                概要 この記事には、受信Webhookのメッセージ形式(パラメーター名や値の指定方法)が記載されています。 受信Webhookの基本的な説明については、こちらをご参照ください。 対応しているパラメーター payload* - JSON messageType - status/event/comment (初期設定の値は「status」です。) streamId - Long commentId - Long attachment - file ...
                              • 受信Webhookの高度なメッセージ形式

                                概要 受信Webhookでは、簡単な形式でテキストを投稿することもできますが、より高度な形式を利用することによって、カード、表、ラベル、箇条書き、画像などを含めた投稿を作成できます。  高度な形式を利用する場合、WebhookのURL宛てに送信するJSONのデータには、投稿内容のテキストの他に追加のパラメーターを含める必要があります。また、高度な形式は、コメントの投稿にも対応しています。 受信Webhookを利用してカード形式のメッセージを投稿する方法 ...

                              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.