Webhook

Webhookを使用すると、Zoho Mailを他の外部アプリケーションと連携できます。Webhookは、外部アプリケーションからのリアルタイムイベントを使用して、1つのアプリケーションで処理をトリガーするために使用されます。Webhookには、Incoming WebhookとOutgoing Webhookの2種類があります。Incoming Webhookは、外部アプリケーションからのリアルタイムイベントを使用して、Zoho Mail内で処理をトリガーするために使用されます。Outgoing Webhookでは、外部アプリケーションで処理をトリガーするように受信メールを設定できます。 

目次

PayPal連携の仕組み

Zoho Mailと外部アプリケーションとの連携を設定するには、1つのアプリケーションでIncoming Webhookを設定し、もう1つのアプリケーションでOutgoing Webhookを設定する必要があります。例えば、外部アプリケーションからストリームグループにイベントを投稿する場合は、次の手順を実行する必要があります。

  1. Zoho MailでIncoming Webhookを設定します。
  2. Incoming Webhookの作成時に生成されたWebhook URLを取得します。
  3. 取得したWebhook URLを使用して、外部アプリケーションでOutgoing Webhookを設定します。

メールを受信した際に外部アプリケーションでイベントをトリガーする場合は、Zoho MailでOutgoing Webhookを、外部アプリケーションでIncoming Webhookを設定する必要があります。 

Incoming Webhook

Incoming Webhookを使用すると、外部アプリケーションで指定したイベントが発生した際に、選択したURLに投稿できます。外部アプリケーションから受信した情報を使用して、ストリームグループにメッセージ、メモ、タスクを投稿するように、Incoming Webhookを設定できます。 

Incoming Webhookの設定

  1. Zoho Mailにサインインしてください。
  2. ［設定］>［連携］>［Developer Space］の順に移動します。 
  3. 左メニューの［設定］セクションで、［Incoming Webhook］を選択します。
  4. ［新規設定の追加］をクリックします。
    Incoming Webhookの設定
  5. 投稿形式を選択します。
    投稿形式の選択
    • メール - Webhookの更新がメールで受信トレイに送信されます。 
    • 投稿/メモ/タスク - Webhookの更新は、投稿/メモ/タスクとして選択したストリームグループに投稿されます。
  6. 前の手順で［メール］を選択した場合は、この手順は省略します。ポスト/メモ/タスクを選択した場合は、設定ページで次の詳細を入力します。必要な投稿を行うためのユーザー名とグループ設定
    • カスタムユーザー名 - この名前はストリームでの投稿に使用されます。
    • グループ - 更新が投稿されるグループ。
  7. 次に、必要に応じて、投稿要求内のデータをWebhook形式に合わせて変更する場合は、［カスタム機能］の下の［書き込み機能］をクリックします。カスタム機能を作成したら、［カスタム機能の選択］をクリックして関数を選択します。カスタム機能の選択
    メモ：
    DREコネクターを使用すると、任意の外部アプリケーションとの接続を確立できます。
  8. ［URLの生成］をクリックして、作成したURLをコピーします。 
    投稿用のURLの作成​

生成されたURLは、選択した外部アプリケーションでOutgoing Webhookを設定する際に使用します。 

メモ：

Incoming Webhookは、グループのモデレーターまたはオーナーのみがストリームグループに設定できます。

留意点

  • ストリーム投稿に@メンションする場合は、メッセージ本文に次の項目を含めます。
    • グループメンバーに@メンションするには、メッセージに@emailIDを含めます。例：Rebeccaに@メンションするには、rebecca@zylker.comを含める
    • グループに@メンションするには、メッセージに@groupを含めます。Webhookに設定されたグループには、自動的にタグが付きます。 
  • Webhook URLは、権限のない個人に開示しないでください。開示された個人は、ストリームグループに更新を投稿できることになります。 
  • Webhook URLを再生成する場合は、使用した場所のすべてで古いURLを新しいURLに置き換える必要があります。 

Outgoing Webhook

Outgoing Webhookを使用すると、外部アプリケーションでイベントをトリガーするようにメール/タスクを設定できます。受信したメール/タスクの詳細を外部アプリケーションに投稿できます。設定のフィルターオプションを使用すると、イベントのトリガーとして機能するメール/タスクを選択できます。 

Outgoing Webhookの設定

Outgoing Webhookのカスタム機能の選択​

  1. Zoho Mailにサインインしてください。
  2. ［設定］>［連携］>［Developer Space］の順に移動します。 
  3. 左メニューの［設定］セクションで、［Outgoing Webhook］を選択します。
  4. ［新規設定の追加］をクリックします。
  5. カスタムユーザー名とWebhook URLを入力したら、設定する項目（メールまたはタスク）を選択する必要があります。 Outgoing WebhookへのURLの入力
    • カスタムユーザー名 - Webhook設定に指定された名前
    • Webhook URL - 外部アプリのIncoming Webhook設定から取得したURL。メールまたはタスクからトリガーされた更新は、このURLに投稿されます。
  6. ［メール］を選択した場合は、次の手順を省略できます。メールの条件タイプ、Webhookのトリガーが必要になる条件を選択する必要があります。 
    • 条件タイプ - フィルター処理の実行方法を選択します。フィルターの詳細については、こちらをクリックしてください。
      ［タグ付きメール］では、特定のタグ（ニュースレター、マーケティングなど）の下にあるメールのみを絞り込みます。特定のタグが付いたメールでWebhookをトリガーする場合は、このオプションを選択します。タグを選択すると、選択したタグのいずれかが受信メールにマークされた場合、または選択したタグの1つ以上が後でメールにマークされた場合に、Webhookがトリガーされます。ただし、［タグ付きメール］を選択した場合は、追加で条件（次の点を参照）を指定することはできません。
    • 条件 - メールの条件タイプを選択した後、必要な条件を指定します。例えば、差出人がrebecca@zylker.comなどの条件です。メール条件の詳細については、こちらをクリックしてください。 
    • メタのみ - このオプションを有効にすると、メールの件名、差出人、宛先、時刻詳細のみが外部アプリケーションに投稿されます。
  7. ［タスク］を選択した場合は、Webhookをトリガーして通知する必要があるタスク処理を選択する必要があります。割り当てられたタスクで選択した処理が発生すると、Webhookがトリガーされます。
    • タスク処理の選択 - 通知を受ける処理を選択します。これを選択すると、割り当てられたタスクで選択した処理が発生した場合のみ、外部アプリケーションでイベントがトリガーされます。
    • グループの選択 - タスクの場合、特定のストリームグループを選択できます。選択したタスク処理が選択したグループで実行された場合にのみ、Webhookがトリガーされます。
    • メタのみ - このオプションを選択すると、次で指定したタスクの詳細のみが外部アプリケーションに投稿されます。
      すべてのデータメタデータのみ説明
      割り当て先割り当て先割り当て先のユーザーID（ZuId）
      assigneeNameassigneeName割り当て先のニックネーム
      displayNamedisplayName割り当て先のフルネーム
      タイトルタイトルタスクのタイトル
      summary タスクの説明
      entityIdentityIdタスクのID
      entityTypeentityType項目を表します。例えば、3はタスク項目であることを示します。
      categoryId カテゴリーのID
      categoryName カテゴリーの名前
      dueDatedueDate期限日（数値指定）。
      優先度 タスクの優先度（数値指定）
      parentTaskId 親のタスクID（トリガーされたタスクがサブタスクの場合）
      nameSpaceIdnameSpaceIdグループのID
      groupNamegroupNameグループの名前
      triggerZuidtriggerZuid処理をトリガーしたアカウントのユーザーID
      ステータスステータスステータス（数値表示）
      statusName タスクのステータス名
      actionactionトリガーされるタスク処理の名前
  8. 必要に応じて、投稿要求内のデータをWebhook形式に合わせて変更する場合は、［カスタム機能］の下の［書き込み機能］をクリックします。カスタム機能を作成したら、［カスタム機能の選択］をクリックして機能を選択します。
  9. ［保存］をクリックしてください。

メモ：

  • 設定で使用されているWebhook URLが長時間応答しない場合、そのOutgoing Webhookは自動的に無効になります。
  • Outgoing Webhook設定を初めて保存すると、投稿要求が開始されます。設定は、投稿要求に対して200応答を受信した場合にのみ保存されます。 

Webhook応答サンプル：

｛
"summary"："こんにちは、Rebecca。金曜日に行う製品プレゼンテーションのためのスライドデッキを共有しました。内容をご確認いただき、ご提案があればお知らせください。よろしくお願いいたします。Paula",
     "sentDateInGMT": 1560866021000,
     "subject": "マーケティング - 製品プレゼンテーション",
     "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 msquot;, Arial, Helvetica, sans-serif;font-size:12pt;"><div>こんにちは、Rebecca。<br/><div><div></div></div><div>金曜日に行う製品プレゼンテーションのためのスライドデッキを共有しました。内容をご確認いただき、ご提案があればお知らせください。<br /></div><div id=""><div><img src="/zm/ImageDisplay?f=1.pngamp;mode=inlineamp;cid=0.28869215260.3894179596053002321.16b695cdb49__inline__img__srcamp;" 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,"
}

Webhookのセキュリティー保護 

Webhookは、要求が本当にZoho Mailからに送信されたかどうかの判定にも使用できるため、セキュリティー保護することをお勧めします。Zoho MailではすべてのWebhook要求に署名を追加して、Webhookを検証できるようにしています。これにより、Webhookにさらなるセキュリティーが追加されます。 

Webhook要求の検証

各Webhook要求には、検証のための署名が含まれています。メッセージの署名に使用されるキーは、x-hook-secretです。このシークレットキーは、Webhookの最初の要求のヘッダーからのみ取得されます。x-hook-signatureは、すべての要求のHTTPヘッダーにあります。ヘッダーは、HMAC SHA256ハッシュのbase64ダイジェストです。ハッシュされたコンテンツは、要求の全本文のバイナリ表現でなければなりません。 

署名を検証するには、x-hook-secretを使用して自分の署名を生成する必要があります。次に、生成した署名を要求ヘッダーの署名と比較して、要求の信頼性を確認します。 

要求の有効性を確認するためのサンプルコードを次に示します。

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

JavaScript：

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

必要な情報は見つかりましたか？

メールお問い合わせ窓口：support@zohomail.com