Webhook
概要
「Webhook」は、バインダへの文書登録、更新、削除のイベントに合わせて、他システムの呼び出しを定義することができます。
定義
Webhookの設定を行うバインダのサイドメニューから「Webhook」メニューをクリックします。
※定義可能な権限は、バインダ管理者またはバインダ設計者です。
Webhookの一覧画面が表示されます。この画面からWebhookの定義を行います。
表 Webhook一覧画面
| 列名 | 説明 |
|---|---|
| ID | WebhookのIDが表示されます。 |
| タイプ | Webhookのタイプが表示されます。 |
| 有効 | Webhookの有効/無効が表示されます。 |
| Webhook名 | Webhookの名前が表示されます。Webhook名をクリックすると定義編集画面が表示されます。 |
| URL | Webhookで呼び出すURLが表示されます。 |
| 説明 | Webhookの説明が表示されます。 |
| 最終更新 | Webhookの最終更新日時と最終更新ユーザが表示されます。 |
| 実行履歴 | 「詳細」ボタンを押下すると実行履歴画面が表示されます。 |
「新規登録」ボタンを押下すると、Webhook新規作成画面が表示されます。
Webhookのタイプを選択します。
※選択できるタイプには、「文書登録」、「文書更新」、「文書削除」があります。
表 Webhookのタイプと呼び出すタイミング
| タイプ | 呼び出すタイミング |
|---|---|
| 文書登録 | ・文書新規登録画面からの文書登録 ・RestAPIでの文書新規 ・公開APIでの文書新規登録（オプション） ・文書作成ロボットでの文書作成 |
| 文書更新 | ・文書更新画面からの文書更新 ・RestAPIでの文書更新 ・公開APIでの文書更新（オプション） ・イベントハンドラ「文書代入」での文書更新 |
| 文書削除 | ・文書削除画面からの文書削除 ・RestAPIでの文書削除 ・公開APIでの文書削除（オプション） |
Webhookの定義画面に必要項目を入力します。
表 Webhook定義画面の項目
| 項目名 | 説明 | 選択方法・指定可能範囲 など |
|---|---|---|
| タイプ | 新規登録時にプルダウンメニューで選択したタイプです。 | 編集できません。 |
| ID | WebhookのIDです。 | 編集できません。 |
| Webhook名* | Webhook名を設定します。 | 任意の文字列を入力します。 |
| 説明 | Webhookの説明を設定します。 | 任意の文字列を入力します。 |
| 有効 | Webhookの有効/無効を設定します。 | チェックボックスにチェックを入れると有効になります。 有効である場合しか送信しません。 |
| URL* | Webhookで呼び出すURLを設定します。 | 「http://」または「https://」で始まる必要があります。 |
| HmacSHA256キー | HmacSHA256キーを設定します。 | 任意のキーを入力します。 送信時に、指定したキーとHmacSHA256アルゴリズムでJSON文に対して、証明コードを計算し、拡張ヘッダ「X-SmartDB-Signature」に保存します。 （証明コードはBase64でエンコードされます。） |
| Basic認証 | Basic認証を利用するかどうかを設定します。 | チェックボックスにチェックを入れると有効になります。 認証のためのユーザ名とパスワードを指定します。 |
| ヘッダ | リクエストヘッダをカスタマイズします。 | チェックボックスにチェックを入れると有効になります。 KEY/VALUEの組み合わせを追加します。 "X-SmartDB"から開始するKEYは予約語のため利用できません。 |
| 条件 | Webhookの送信条件を設定します。 | 「選択」ボタンを押下して、フィルター定義を選択します。 |
| 通知メール | Webhookの処理失敗時に通知します。通知方法はメールのみとなります。 | チェックボックスにチェックを入れると有効になります。デフォルトは「ON」です。 |
| 宛先* | 通知メールの宛先を指定します。 | 指定したい宛先のチェックボックスにチェックします。 デフォルトの宛先は「バインダ管理者」です。 |
※ [*]は入力必須項目です。
既存のWebhookを編集する場合は、Webhook一覧画面でWebhook名をクリックします。
Webhookのリクエスト内容について
Webhook実行時にSmartDBから送信されるリクエストの内容について記載しています。 実際に送信した内容は実行履歴の「詳細」から確認が可能です。
リクエスト情報
| 項目 | 値 | 説明 |
|---|---|---|
| メソッド | POST | 固定 |
ヘッダ情報
| 項目 | 値 | 説明 |
|---|---|---|
| Content-Type | application/json; charset=UTF-8 | 固定 |
| X-SmartDB-Event | DOCUMENT_CREATED DOCUMENT_UPDATED DOCUMENT_DELETED |
Webhookのタイプに対応した値 |
| X-SmartDB-Version | [version番号] | 5.3.0 などSmartDBのバージョン番号 |
| X-SmartDB-Request-ID | [ユニークID] | 1234 などWebhookリクエストのユニークID |
| X-SmartDB-Signature | [HmacSHA256キー] | Webhook設定画面で指定したHmacSHA256キーをBase64でエンコードした値 |
| カスタムヘッダ | [設定内容] | Webhook設定画面のヘッダで指定したKEY/VALUE |
ボディ情報
ボディで送信される情報について記載しています。
一部の項目については省略されている場合があります。
ボディの要素
| 項目 | 説明 |
|---|---|
| binder | バインダ情報。詳細はバインダ情報を参照。 |
| documents | 文書情報。詳細は文書情報を参照。 |
| oldDocuments | 更新前の文書情報。更新時のみ存在する項目。詳細は文書情報を参照。 |
| updatedItems | 更新した部品の情報。更新時のみ存在する項目。詳細は部品情報を参照。 |
| operator | 操作ユーザ。詳細はユーザ情報を参照。 |
| timestamp | Webhookを送信した時間。 |
バインダ情報
| 項目 | 説明 |
|---|---|
| created | 作成ユーザ。詳細はユーザ情報を参照 |
| created_at | 作成日時 |
| id | バインダID |
| name | バインダ名 |
| parent_id | 親キャビネットID |
| type | バインダのタイプ。1:バインダ |
| updated | 更新ユーザ。詳細はユーザ情報を参照 |
| update_at | 更新日時 |
| description | 説明 |
| owner | 主管部署。詳細はグループ情報を参照。 |
文書情報
| 項目 | 説明 |
|---|---|
| created | 作成ユーザ。詳細はユーザを参照。 |
| created_at | 作成日時 |
| id | バインダID |
| updated | 更新ユーザ。詳細はユーザを参照。 |
| update_at | 更新日時 |
| item | 部品情報。詳細は部品情報を参照。 |
部品情報
部品情報は対象部品の値が全て含まれ、配列で表現されます。
| 項目 | 説明 |
|---|---|
| id | 部品id |
| name | 部品名 |
| type | 部品タイプ |
| value | 入力された値 |
ユーザ情報
| 項目 | 説明 |
|---|---|
| id | ユーザの内部ID（MID） |
| key | メールアドレス |
| name | ユーザ名 |
| type | アカウントのタイプ。1:ユーザ |
| メールアドレス | |
| primary | プライマリ所属組織の内部ID（GID） |
| primaryGroupName | プライマリ所属組織の名前 |
| status | ユーザの状態。0:一般ユーザ、8:ログイン不能ユーザ |
グループ情報
| 項目 | 説明 |
|---|---|
| id | グループの内部ID（GID） |
| name | グループ名 |
| type | アカウントのタイプ。2:組織 |
| status | グループの状態。0:有効、8:廃止グループ |
実行履歴
Webhook一覧画面の実行履歴列にある「詳細」ボタンを押下すると、実行履歴が表示されます。
※実行履歴が参照できるのは、バインダ管理者のみです。
実行履歴の「詳細」をクリックすると、httpリクエストとレスポンスの詳細が確認できます。
ステータスが失敗の場合は、エラーの詳細が確認できます。
httpリクエストの詳細中にある「再送信」ボタンを押下すると、httpリクエストが再送信されます。
表 実行履歴の項目
| 項目 | 説明 |
|---|---|
| リクエストID | 送信する際に拡張ヘッダ「X-SmartDB-Request-ID」に設定されるシステム全体で唯一のIDです。 |
| ステータス | 該当送信のステータスです。可能な値： ・キューイング：リクエストは送信キューにいます。送信待ちです。 ・成功：送信は成功しました。つまり、該当Httpレスポンスコードは200です。 ・不明：送信は完了しましたが、該当Httpレスポンスコードは200以外になります。 ・タイムアウト：キューイングのまま送信されない場合、30分でタイムアウトになります。 ・失敗：送信時に、エラーが発生しました。 |
| 作成時間 | リクエストの作成時間。つまり、送信キューに投入する時間です。 |
| 開始時間 | リクエストをキーからデキューされて、実際送信するの時間です。 |
| 実行時間（秒） | 送信がかかった時間です。単位：秒。（送信完了時間 - 開始時間） |
| レスポンスコード | 送信のレスポンスのHttpステータスコードです。 |
| 「詳細」ボタン | クリックすると、リクエストとレスポンスの詳細情報を表示します。 |
| 「再送信」ボタン | ステータスは「キューイング」じゃない場合表示します。クリックすると、再送信できます。 再送信する時、新しいリクエストを作成します。つまり、新しい履歴行が生成されます。 |
制限事項
- webhookリクエストは5分でタイムアウトします。
- webhookリクエストのbodyは改変できません。
- webhookはキューイングされて順番に実施されます。
- キューイングされたwebhookは並行して処理されるため、文書の更新順と処理順は異なる場合があります。
- 送信までに時間がかかる場合があります。