Webhookブロックのヘッダー

Webhookブロックのヘッダー

Webhookブロックを通じてAPIリクエストを送信するにあたって、ヘッダーはとても重要です。ヘッダーに含まれている情報をもとに、外部アプリ／システム側でAPIリクエストの識別、承認が行われます。
以下では、Webhookブロックのヘッダーの概要やよくある質問について説明します。

参考情報：自動ガイドボットのWebhookブロックの概要 

ヘッダーとは   

ヘッダーとは、キーと値の組み合わせです。Webhookのリクエストと共に送信されます。ヘッダーの情報をもとに、外部アプリ／システム側で送信元の識別が行われたり、リクエストの内容の説明が行われたりします。

ヘッダーの例は、以下のとおりです。
  1. Key: Authorization
  2. Value: Bearer your-access-token
別のヘッダーの例は、以下のとおりです。
  1. Key: Content-Type
  2. Value: application/json
ヘッダーは、チャットの利用者には表示されません。データ通信が安全に行われるように、システム側でのみ機能します。 



ヘッダーを使用するタイミング   

ヘッダーを使用する主なタイミングは、以下のとおりです。
  1. APIの認証が必要（例：OAuth、APIトークン）
  2. リクエストの本文の形式の設定が必要（通常はJSON）
  3. Zohoサービスなどの外部アプリ／システムにおいて、外部組織IDやポータルIDなどの追加情報が必要
  4. リクエストボディまたはURLに表示したくない、システムに関する機密情報を安全に送信したい
 ヘッダーは、Webhookブロックの［ヘッダー］のセクションで追加できます。こちらから、キーと値の組み合わせを設定することが可能です。 

ヘッダーが重要な理由   

APIの実行においてヘッダーが重要な理由は、以下のとおりですなお、外部アプリ／システムにAPIリクエストを送信する際に、ヘッダーを使用して機密情報をマスキングすることもできます。
  1. リクエストの送信元を認証できる
  2. リクエストボディの形式を指定できる（例：JSON、XML）
  3. システムに関する情報を追加できる（例：組織ID、ポータルID）
  4. サーバーに対してリクエストを安全に処理するように指定できる
ヘッダーの情報が正しくない場合、リクエストが却下されたり、エラーが発生したりする可能性があります。 

主に使用されるヘッダー
主に使用されるヘッダー
APIの実行時に主に使用されるヘッダーは、以下のとおりです。

ヘッダーのキー
値の例
使用目的
Authorization
Bearer ya29.a0AfH6???
アクセストークンを使用してリクエストを認証する
Content-Type
application/json
リクエストボディの形式をサーバー側に伝える
orgId
1234567890
APIの送信元となるZohoの組織を識別する
portalId
zylker-support
APIの送信元となる部門を識別する

 1件のWebhookのリクエストに追加できるヘッダーの上限は、20件です。 
使用例
ボットを通じて、Zoho Desk APIを使用して問い合わせを更新したいとします。更新するには、認証済みのPUTリクエストを送信する必要があります。

この場合、ヘッダーを以下のように設定します。
  1. Authorization: Bearer 1000.abcdeXYZ.your-access-token
  2. orgId: 123456789
  3. Content-Type: application/json
これにより、以下の内容をシステム側に知らせることができます。
  1. 送信元の情報（Authorization）
  2. 送信元のZohoの組織（orgId）
  3. リクエストボディの形式がJSONであること（Content-Type）
ヘッダーがない場合、Zohoのサーバーで処理を行うことはできません。

ヘッダーの安全性   

ヘッダーの情報は、チャットの利用者に対して表示されません。以下の機密情報に関して、安全に取り扱うことができます。
  1. OAuthトークン
  2. APIキー
  3. 内部参照用の組織ID
ただし、以下の点にご注意ください。
  1. ヘッダーの情報をボットのメッセージの本文に追加しない
  2. トークンを安全に保存し、定期的に変更する
  3. 「https://」からはじまる、セキュア接続で保護されているエンドポイントを使用して、データ通信を暗号化する
 

ヘッダーを使用するメリット   

  1. 認証情報を安全に取り扱うことができます
  2. リクエストの形式を適切に指定できます
  3. 外部アプリ／システムに対して追加情報を伝えることができます
  4. チャットの利用者に対して、機密情報を非表示にできます
  5. データ通信を保護できます

使用に関するヒント   

  1. ヘッダーの要件については、該当のサービスのAPIドキュメントをご参照ください
  2. 必要に応じて、トークンの前に「Bearer」を使用してください（例：Bearer abc123token）
  3. 必要な情報のみをヘッダーに追加してください
  4. ヘッダーを本番環境で使用する前に、テスト環境で検証を行うことをお勧めします。
  5. 必要にトークンを更新してください（特にOAuthを使用したシステムの場合）

参考情報：自動ガイドボットのWebhookブロックの概要