Webhook概要

SmartHR Webhook の仕様について

設定方法

Webhook の設定は管理画面の「外部システム連携」より行えます。
設定の際には、以下の項目をご登録いただきます。
項目説明
URLWebhook から POST されるデータを受け取る URL
EventWebhook 発動のトリガーとなるイベント種別
SecretToken
（任意）		SmartHR からの送信データであることを確認するためのシークレットトークン
このトークンは X-SmartHR-Token というリクエストヘッダで送信されます。
説明 （任意）登録した Webhook 設定の説明

データの受信

Webhook では指定された URL に POST でデータが送信されます。SmartHR サーバからアクセスできない URL やプライベートネットワークアドレスではご利用いただけません。データ受信後はステータスコード 200 番台で応答するようお願いいたします。
200 番台以外のレスポンスを検知した場合、もしくは60秒以内に応答がなかった場合は、送信失敗とみなしてリトライを行います。リトライ送信は約3日間で最大17回試行されます。（サンドボックス環境では約8分間で最大5回施行されます）
リトライ上限に達して送信失敗した場合は、対象の Webhook が無効化されます。

イベント

Webhook が発動されるイベントには以下のものがあります。
イベントID発動タイミング送信オブジェクト
crew_created従業員データが作成されたタイミングで発動Crew
crew_updated従業員データが更新されたタイミングで発動Crew
crew_deleted従業員データが完全に削除されたタイミングで発動Crew
crew_imported従業員データがファイルを使って取り込まれたタイミングで発動CrewImportResult
dependent_created家族データが作成されたタイミングで発動Dependent
dependent_updated家族データが更新されたタイミングで発動Dependent
dependent_deleted家族データが完全に削除されたタイミングで発動Dependent
dependent_imported家族データがファイルを使って取り込まれたタイミングで発動DependentImportResult

送信データ

Webhook から POST されるデータは、以下の構造を持つ JSON となっています。
プロパティ型内容
eventString発動したイベントの ID
triggered_atStringイベントが発動した日時
senderCrewイベントを発動させた従業員。従業員データと紐付かないアカウントの場合は null となります。
イベントごとの送信オブジェクト-詳細は下記をご参照ください。
各イベントが持つ送信オブジェクトは以下の通りです。

Crew

（プロパティ名: crew）
「従業員」エンドポイントで取得可能な Crew オブジェクトと同じ構造を持ちますが、出力される項目が限定されています。Payload の全体イメージは以下の通りです。
{
  "id": "string",
  "user_id": "string",
  "biz_establishment_id": "string",
  "emp_type": "board_member",
  "employment_type": {
    "id": "string",
    "name": "string",
    "preset_type": "board_member",
    "updated_at": "2021-03-17T00:00:00.000Z",
    "created_at": "2021-03-17T00:00:00.000Z"
  },
  "emp_status": "employed",
  "emp_code": "string",
  "last_name": "string",
  "first_name": "string",
  "last_name_yomi": "string",
  "first_name_yomi": "string",
  "business_last_name": "string",
  "business_first_name": "string",
  "business_last_name_yomi": "string",
  "business_first_name_yomi": "string",
  "birth_at": "2021-03-17",
  "gender": "male",
  "tel_number": "string",
  "email": "string",
  "address": {
    "id": "string",
    "country_number": "string",
    "zip_code": "string",
    "pref": "string",
    "city": "string",
    "street": "string",
    "building": "string",
    "literal_yomi": "string"
  },
  "address_head_of_family": "string",
  "address_relation_name": "string",
  "resident_card_address": {
    "id": "string",
    "country_number": "string",
    "zip_code": "string",
    "pref": "string",
    "city": "string",
    "street": "string",
    "building": "string",
    "literal_yomi": "string"
  },
  "resident_card_address_head_of_family": "string",
  "resident_card_address_relation_name": "string",
  "profile_images": [
    {
      "size_type": "thumb",
      "height": 20,
      "width": 20,
      "url": "string"
    },
    {
      "size_type": "small",
      "height": 120,
      "width": 120,
      "url": "string"
    },
    {
      "size_type": "medium",
      "height": 230,
      "width": 230,
      "url": "string"
    },
    {
      "size_type": "large",
      "height": 500,
      "width": 500,
      "url": "string"
    },
    {
      "size_type": "original",
      "height": 20,
      "width": 20,
      "url": "string"
    }
  ],
  "emergency_address": {
    "id": "string",
    "country_number": "string",
    "zip_code": "string",
    "pref": "string",
    "city": "string",
    "street": "string",
    "building": "string",
    "literal_yomi": "string"
  },
  "emergency_relation_name": "string",
  "emergency_last_name": "string",
  "emergency_first_name": "string",
  "emergency_last_name_yomi": "string",
  "emergency_first_name_yomi": "string",
  "emergency_tel_number": "string",
  "department": "string",
  "departments": [
    {
      "id": "string",
      "name": "string",
      "position": 0,
      "code": "string",
      "parent": {},
      "children": [
        {}
      ],
      "updated_at": "2021-03-17T00:00:00.000Z",
      "created_at": "2021-03-17T00:00:00.000Z"
    }
  ],
  "position": "string",
  "occupation": "string",
  "entered_at": "2021-03-17",
  "resigned_at": "2021-03-17",
  "resigned_reason": "string",
  "resume1": {
    "file_name": "string",
    "url": "string"
  },
  "resume2": {
    "file_name": "string",
    "url": "string"
  },
  "bank_accounts": [
    {
      "bank_code": "string",
      "bank_branch_code": "string",
      "account_type": "saving",
      "account_number": "string",
      "account_holder_name": "string",
      "bankbook_image": {
        "file_name": "string",
        "content": "string"
      },
      "bank_account_setting_id": "string"
    }
  ],
  "nearest_station_and_line": "string",
  "commutation_1_expenses": 0,
  "commutation_1_period": "commutation_period_1_month",
  "commutation_1_single_fare": 0,
  "commutation_2_expenses": 0,
  "commutation_2_period": "commutation_period_1_month",
  "commutation_2_single_fare": 0,
  "emp_ins_qualified_at": "2021-03-17",
  "emp_ins_disqualified_at": "2021-03-17",
  "soc_ins_qualified_at": "2021-03-17",
  "soc_ins_disqualified_at": "2021-03-17",
  "having_spouse": true,
  "custom_fields": [
    {
      "value": "string",
      "template": {
        "id": "string",
        "name": "string",
        "type": "date",
        "elements": [
          {
            "id": "string",
            "name": "string",
            "physical_name": "string",
            "position": 0
          }
        ],
        "group_id": "string",
        "group": {
          "id": "string",
          "name": "string",
          "position": 0,
          "access_type": "read_and_update",
          "templates": [
            {}
          ],
          "updated_at": "2021-03-17T00:00:00.000Z",
          "created_at": "2021-03-17T00:00:00.000Z"
        },
        "hint": "string",
        "scale": 0,
        "separated_by_commas": true,
        "position": 0,
        "updated_at": "2021-03-17T00:00:00.000Z",
        "created_at": "2021-03-17T00:00:00.000Z"
      }
    }
  ],
  "created_at": "2021-03-17T00:00:00.000Z",
  "updated_at": "2021-03-17T00:00:00.000Z"
}

CrewImportResult

（プロパティ名: crew_import_result）ファイルの取り込みによって一括で登録・更新された従業員情報がまとめて出力されます。登録された従業員は created_crews に、更新された従業員は updated_crews にそれぞれ分けられ、Crew のリストとして表現されます。Payload の全体イメージは以下の通りです。
{
  "event": "crew_imported",
  "sender": null,
  "triggered_at": "2021-03-17T00:00:00+09:00",
  "crew_import_result": {
    "created_crews": [],
    "updated_crews": []
  }
}

Dependent

（プロパティ名: dependent）「家族情報」エンドポイントで取得可能な Dependent オブジェクトと同じ構造を持ちますが、出力される項目が限定されています。Payload の全体イメージは以下の通りです。
{
  "id": "string",
  "crew_id": "string",
  "relation": {
    "id": "string",
    "name": "string",
    "preset_type": "string",
    "is_child": true,
    "position": 0,
    "created_at": "2021-03-17T00:00:00.000Z",
    "updated_at": "2021-03-17T00:00:00.000Z"
  },
  "is_spouse": true,
  "last_name": "string",
  "first_name": "string",
  "last_name_yomi": "string",
  "first_name_yomi": "string",
  "created_at": "2021-03-17T00:00:00.000Z",
  "updated_at": "2021-03-17T00:00:00.000Z"
}

DependentImportResult

（プロパティ名: dependent_import_result）ファイルの取り込みによって一括で登録・更新された家族情報がまとめて出力されます。登録された家族は created_dependents に、更新された家族は updated_dependents にそれぞれ分けられ、Dependent のリストとして表現されます。Payload の全体イメージは以下の通りです。
{
  "event": "dependent_imported",
  "sender": null,
  "triggered_at": "2021-03-17T00:00:00+09:00",
  "dependent_import_result": {
    "created_dependents": [],
    "updated_dependents": []
  }
}

送信の制御

API リクエスト時に以下のパラメータを付与すると、そのリクエストによるデータ更新では Webhook が送信されなくなります。
skip_sending_webhook=true