Webhook機能で外部システムに送信されるJSONデータの詳細仕様について説明します。この情報を参考に、受信側システムで適切なデータ処理を実装してください。
📊 送信データの概要
WebhookではJSON形式で以下の8つの主要なデータオブジェクトが送信されます。各オブジェクトには申請書類に関する詳細な情報が含まれています。
💡 主要データオブジェクト
- record_info:申請書類の詳細情報(フォーム項目の値等)
- reference_info:参照書類一覧
- approval_status_info:承認状況一覧
- circulate_status_info:回覧状況一覧
- history_info:変更履歴一覧
- document_info:書類情報
- url_info:各申請書類画面へのリンク
- action_info:Webhookの実行情報
- status_transition_info:ステータス遷移情報
📝 データ構造詳細
1. record_info(申請書類詳細情報)
申請書類の詳細情報が配列形式で含まれます。フォーム項目の値と、Boxフォルダ情報が含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
id |
string | 項目のIDが入ります |
label |
string | 項目の表示ラベルが入ります |
value |
string | 項目に入力された値が入ります |
input_type |
string | 項目の入力形式が入ります |
code |
string | 入力形式が社員選択⇒社員番号、部門選択⇒部門コード、任意マスタ選択⇒マスタコード、申請データ選択⇒管理IDの場合、選択したデータのIDが入ります |
💡 Box連携情報
record_infoには標準で「box_folder_id」項目が含まれます。Boxのアップロード先を管理者が設定している、または申請時にアップロード先フォルダを選択していた場合は、valueにBoxのフォルダIDが入ります。
2. reference_info(参照書類一覧)
参照書類一覧が配列形式で含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
management_id |
string | 管理IDが入ります |
apply_date |
string | 申請年月日が入ります |
apply_title |
string | 件名が入ります |
apply_user_id |
string | 申請者の社員番号が入ります |
apply_user_name |
string | 申請者名が入ります |
apply_dept_code |
string | 申請部門の部門コードが入ります |
apply_dept_name |
string | 申請部門名が入ります |
status_info |
string | ステータス情報が入ります |
approval_completion_date |
string | 承認完了日が入ります |
3. approval_status_info(承認状況一覧)
承認状況一覧が配列形式で含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
employee_code |
string | 申請者/承認者のユーザIDが入ります |
employee_name |
string | 申請者/承認者の社員名が入ります |
department_code |
string | 部門コードが入ります |
department_name |
string | 部門名が入ります |
position_code |
string | 役職コードが入ります |
position_name |
string | 役職名が入ります |
status_name |
string | ステータス名が入ります |
approval_status |
string | 申請/承認状況が入ります |
approval_date |
string | 申請/承認日時が入ります |
comment |
string | コメントが入ります |
4. circulate_status_info(回覧状況一覧)
回覧状況一覧が配列形式で含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
employee_code |
string | 申請者/承認者のユーザIDが入ります |
employee_name |
string | 申請者/承認者の社員名が入ります |
department_code |
string | 部門コードが入ります |
department_name |
string | 部門名が入ります |
position_code |
string | 役職コードが入ります |
position_name |
string | 役職名が入ります |
status_name |
string | ステータス名が入ります |
approval_status |
string | 申請/承認状況が入ります |
approval_date |
string | 申請/承認日時が入ります |
comment |
string | コメントが入ります |
5. history_info(変更履歴一覧)
変更履歴一覧が配列形式で含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
change_date |
string | 変更日時が入ります |
changer_id |
string | 変更者のユーザIDが入ります |
changer_name |
string | 変更者の社員名が入ります |
change_content |
string | 変更内容が入ります |
change_screen |
string | 変更画面が入ります |
6. document_info(書類情報)
書類情報が配列形式で含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
document_id |
string | 書類IDが入ります |
document_name |
string | 書類名が入ります |
version |
string | 書類の版数が入ります |
description |
string | 書類の説明が入ります |
workflow_id |
string | ワークフローIDが入ります |
form_id |
string | フォームIDが入ります |
form_version |
string | フォームの版数が入ります |
7. url_info(リンク情報)
各申請書類画面へのリンクがオブジェクト形式で含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
apply_url |
string | 申請書類のURLが入ります |
approve_url |
string | 承認書類のURLが入ります |
reference_url |
string | 書類参照のURLが入ります |
inspection_url |
string | 保管書類のURLが入ります |
circulate_url |
string | 回覧書類のURLが入ります |
jurisdiction_url |
string | 所管書類のURLが入ります |
8. action_info(アクション情報)
Webhookの実行情報がオブジェクト形式で含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
action_time |
string | Webhookの実行日時が入ります |
action_type |
string | Webhookのトリガータイプが入ります ・申請時:apply ・承認時:approve ・承認完了時:complete |
9. status_transition_info(ステータス遷移情報)
ステータス遷移情報がオブジェクト形式で含まれます。
| フィールド名 | 型 | 説明 |
|---|---|---|
route_id |
string | ルートIDが入ります |
next_status_info |
object | 遷移先のステータス情報が入ります(status_noとstatus_nameが含まれます) |
status_info |
object | 現在のステータス情報が入ります(status_noとstatus_nameが含まれます) |
status_no |
string | ステータス番号が入ります |
status_name |
string | ステータス名が入ります |
🔧 データ処理のポイント
💡 実装時の注意点
- 配列データの確認:record_info、reference_info、approval_status_info、circulate_status_info、history_info、document_infoは配列形式です
- オブジェクトデータの確認:url_info、action_info、status_transition_infoはオブジェクト形式です
- NULL値の処理:一部のフィールドはNULLになる場合があります(適切なNULLチェックを実装)
- 文字エンコーディング:すべてのテキストデータはUTF-8エンコーディングです
- 特殊項目の処理:record_infoのcode項目は、入力形式により格納される値が異なります
📋 JSONサンプル(一部抜粋)
{
"record_info": [
{
"id": "box_folder_id",
"label": "Boxフォルダ",
"value": "123456789",
"input_type": "box_folder",
"code": ""
},
{
"id": "f_apply_title",
"label": "件名",
"value": "経費精算申請",
"input_type": "text",
"code": ""
},
{
"id": "f_apply_user",
"label": "申請者",
"value": "田中太郎",
"input_type": "employee",
"code": "00001"
}
],
"approval_status_info": [
{
"employee_code": "00001",
"employee_name": "田中太郎",
"department_code": "10001",
"department_name": "営業部",
"position_code": "P001",
"position_name": "課長",
"status_name": "申請",
"approval_status": "申請済み",
"approval_date": "2024-03-15 10:00:00",
"comment": "承認をお願いします"
}
],
"action_info": {
"action_time": "2024-03-15 10:00:00",
"action_type": "apply"
}
}🎯 まとめ
Webhookデータの詳細仕様を理解して、外部システムとの効果的な連携を実現してください。
🔑 データ処理成功のポイント
- 各データオブジェクトの型(配列/オブジェクト)を正確に理解した実装
- 配列データの反復処理とNULL値の適切な処理
- record_infoのcode項目における入力形式別の値解釈
- エラーハンドリングとログ記録の実装
Webhook連携の設定方法について詳しく知りたい場合は、「Webhookを設定するには?」の記事をご参照ください。