Webhookエンドポイントとは?
Webhook エンドポイントは、イベントが発生したときに Tiro が HTTP POST リクエストを送信する URL です。Tiro Platform に登録すると、API をポーリングせずにイベントを受け取れます。Webhook の仕組み
- 設定する: アプリケーションに webhook の endpoint を用意します
- 登録する: 受け取りたいイベントを処理するために、endpoint を追加します
- 受信する: イベントが発生すると即座に通知が届きます
- 処理する: アプリケーションでイベントのデータを処理します
イベントとリソースの構造
Webhook は イベント(Events) と リソース(Resources) を中心に構成されています。イベント
イベントは、ワークスペースで発生したアクションを表します。詳しくは Note Events、Note Document Events、Note Summary Events、FolderNote Events、音声ファイル API の概要 をご覧ください。 Webhook イベントにはメタデータのみが含まれ、通常は数百 KB 未満です。transcript や script などの大きなコンテンツは別の API から取得してください。リソース
リソースは、イベントの対象となる主要なエンティティです。Note: 個々のノートのリソースNoteDocument: ノートから生成されるテンプレートベースのドキュメントNoteSummary: ノートに対して AI が生成する要約FolderNoteRelation: フォルダとノートの関係
Webhook の payload 構造
すべての webhook イベントは、標準の Event Structure 構造に従います。セキュリティ
Webhook リクエストは、Authorization ヘッダーに設定された secret key で認証されます。検証の例
配信とリトライ
- Method: HTTP POST
- Content-Type:
application/json - Timeout: 60 秒
- Retries: 最大 5 回のリトライ(合計 6 回の試行)。exponential backoff で実施します
- Success: 2xx の HTTP ステータスコードであれば成功とみなします
リトライのスケジュール
- 15 秒後
- 30 秒後
- 5 分後
- 30 分後
- 2 時間後
はじめに
- endpoint を用意する: POST リクエストを受信できる HTTP の endpoint を作成します
- webhook を設定する: Tiro Platform で webhook の endpoint を登録します
- イベントを処理する: アプリケーションで受信した webhook の payload を処理します
ユーザー Webhook は、ユーザーアカウントに紐づく 1 つの endpoint です。ユーザーが現在アクセスできるすべてのワークスペースのイベントをまとめて受け取ります。ノート・要約・ドキュメント・フォルダのイベントは、そのユーザーがアクセスできるリソースについて配信されます。payload 最上位の
workspaceGuid でイベントの送信元ワークスペースを判別してください。ワークスペースシステム Webhook はワークスペース単位で登録・管理し、紐づく 1 つのワークスペースのイベントを受け取ります。ノートイベント(
note.*、note_summary.*、note_document.*)とフォルダイベント(folder.note.*)は、ワークスペースの全メンバーに共有されたフォルダのノートのみを配信します。個人フォルダのノート、一部のメンバーにのみ共有したフォルダのノート、どのフォルダにも入れていないノートには、イベントが配信されません。音声ファイルジョブのイベントは、この範囲の対象外です。この範囲が適用される前に登録されたシステム Webhook エンドポイントは、当面これまでの動作を維持し、順次移行される予定です。詳しい範囲はシステムAPIキーが読み取るノートの範囲をご覧ください。Organization 契約をご利用の場合は、組織単位の webhook も登録できます。組織の endpoint は、組織に所属するすべてのワークスペースのイベントをワークスペースの区別なく受け取り、payload に
organizationGuid が含まれます。詳しくは組織単位で連携するをご覧ください。