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

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

留意点

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

Outgoing Webhook

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

Outgoing Webhookの設定

​

1. Zoho Mailにサインインしてください。
2. ［設定］>［連携］>［Developer Space］の順に移動します。 
3. 左メニューの［設定］セクションで、［Outgoing Webhook］を選択します。
4. ［新規設定の追加］をクリックします。
   
5. カスタムユーザー名とWebhook URLを入力したら、設定する項目（メールまたはタスク）を選択する必要があります。 
   • カスタムユーザー名 - Webhook設定に指定された名前
   • Webhook URL - 外部アプリのIncoming Webhook設定から取得したURL。メールまたはタスクからトリガーされた更新は、このURLに投稿されます。
6. ［メール］を選択した場合は、次の手順を省略できます。メールの条件タイプ、Webhookのトリガーが必要になる条件を選択する必要があります。 
   • 条件タイプ - フィルター処理の実行方法を選択します。フィルターの詳細については、こちらをクリックしてください。
     ［タグ付きメール］では、特定のタグ（ニュースレター、マーケティングなど）の下にあるメールのみを絞り込みます。特定のタグが付いたメールでWebhookをトリガーする場合は、このオプションを選択します。タグを選択すると、選択したタグのいずれかが受信メールにマークされた場合、または選択したタグの1つ以上が後でメールにマークされた場合に、Webhookがトリガーされます。ただし、［タグ付きメール］を選択した場合は、追加で条件（次の点を参照）を指定することはできません。
   • 条件 - メールの条件タイプを選択した後、必要な条件を指定します。例えば、差出人がrebecca@zylker.comなどの条件です。メール条件の詳細については、こちらをクリックしてください。 
   • メタのみ - このオプションを有効にすると、メールの件名、差出人、宛先、時刻詳細のみが外部アプリケーションに投稿されます。
7. ［タスク］を選択した場合は、Webhookをトリガーして通知する必要があるタスク処理を選択する必要があります。割り当てられたタスクで選択した処理が発生すると、Webhookがトリガーされます。
   • タスク処理の選択 - 通知を受ける処理を選択します。これを選択すると、割り当てられたタスクで選択した処理が発生した場合のみ、外部アプリケーションでイベントがトリガーされます。
   • グループの選択 - タスクの場合、特定のストリームグループを選択できます。選択したタスク処理が選択したグループで実行された場合にのみ、Webhookがトリガーされます。
   • メタのみ - このオプションを選択すると、次で指定したタスクの詳細のみが外部アプリケーションに投稿されます。

     すべてのデータ	メタデータのみ	説明
     割り当て先	割り当て先	割り当て先のユーザーID（ZuId）
     assigneeName	assigneeName	割り当て先のニックネーム
     displayName	displayName	割り当て先のフルネーム
     タイトル	タイトル	タスクのタイトル
     summary		タスクの説明
     entityId	entityId	タスクのID
     entityType	entityType	項目を表します。例えば、3はタスク項目であることを示します。
     categoryId		カテゴリーのID
     categoryName		カテゴリーの名前
     dueDate	dueDate	期限日（数値指定）。
     優先度		タスクの優先度（数値指定）
     parentTaskId		親のタスクID（トリガーされたタスクがサブタスクの場合）
     nameSpaceId	nameSpaceId	グループのID
     groupName	groupName	グループの名前
     triggerZuid	triggerZuid	処理をトリガーしたアカウントのユーザーID
     ステータス	ステータス	ステータス（数値表示）
     statusName		タスクのステータス名
     action	action	トリガーされるタスク処理の名前

8. 必要に応じて、投稿要求内のデータをWebhook形式に合わせて変更する場合は、［カスタム機能］の下の［書き込み機能］をクリックします。カスタム機能を作成したら、［カスタム機能の選択］をクリックして機能を選択します。
9. ［保存］をクリックしてください。

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