変更承認後のWebhook通知

2024/4/15 17:152026/10/8 19:55

この記事では、変更が承認されたときに外部システムへ通知を送る「Webhook通知」の設定方法と、通知の条件・内容・送信時の挙動について説明します。

📋 関連記事 Webhook通知を設定するには、ロールの機能制限設定で「Webhook通知」が有効になっている必要があります。設定方法はロール毎の機能制限設定を参照してください。

Webhook通知とは

Webhook通知は、YESODで変更が承認されたタイミングで、あらかじめ指定したURLへ変更内容を送信する機能です。入社・退職などの変更を、連携先のシステムへすぐに伝えたい場合に利用できます。

項目	内容
送信のきっかけ	変更の承認
送信先	Webhook作成時に指定したURL
送信方式	HTTP POST（JSON形式）
通知される変更	入社／退職／雇用形態変更／入社取り消し／メンバー情報変更（詳細は「通知の条件と内容」を参照）

承認された変更に、Webhookで選択した通知条件と合致する変更が含まれていた場合に、通知が送信されます。

💡 ポイント 変更予定日が未来の日付の変更でも、変更予定日ではなく承認した時点で通知が送信されます。通知先のシステムでは、通知に含まれる変更日をもとに処理してください。

左メニューから「設定」をクリックします。

設定メニューから「Webhook通知」をクリックし、ヘッダー右上の「Webhookを追加」をクリックします。

「新規Webhook」のダイアログで次の項目を入力し、「保存」をクリックします。

項目	必須／任意	内容
Webhook名称	必須	一覧に表示される名称を入力します
Webhook URL	必須	通知の送信先URLを入力します
実行ロール	必須	通知に含める項目の範囲を決めるロールを選択します。通知される内容は、このロールがアクセスできる範囲に制限されます（詳細は「通知に含まれる項目と実行ロール」を参照）
承認時通知/通知内容	必須	通知したい変更の種類を選択します。複数選択できます（入社／退職／雇用形態変更／入社取り消し／メンバー情報変更）
メモ	任意	用途や連携先など、自由記述のメモを残せます

保存すると、Webhook通知の一覧に追加されます。

💡 ポイント 作成したWebhookの内容を変更したい場合は、一覧右側のメニューから削除し、作り直してください。

Webhookを作成したら、実際に通知を受け取れるかをテストできます。

Webhook通知の一覧で、対象のWebhookの「テスト」をクリックします。

設定した通知条件に合うダミーのデータが、設定したURLに送信されます。画面に送信結果が表示されるので、あわせて通知先のシステムで受信できたことを確認してください。

選択した通知条件ごとに、次のタイミングで通知が送信されます。

名称	条件	通知される内容
入社	任意の会社へ所属したとき（兼務追加も含む）	「入社日」時点でのメンバーの項目
退職	任意の会社から所属が外れたとき（兼務解除も含む）	「退職日」時点でのメンバーの項目
雇用形態変更	会社への所属追加・解除以外の操作で、任意の会社での雇用形態が追加・変更・削除されたとき	「雇用形態変更」の発生日時点でのメンバーの項目
入社取り消し	入社が取り消されたとき（再入社の取り消しは対象外）	最初の「入社日」時点でのメンバーの項目
メンバー情報変更	メンバーに関するあらゆる変更が承認されたとき（ロールの付与・剥奪、入退社予定日の変更、入社取り消し、再入社取り消しも含む）	①変更予定日時点の、変更が適用される前のメンバーの項目 ②項目の値の変更の種別（追加・削除など） ③通知のきっかけになったイベントの情報

⚠️ 注意所属している会社が削除されたことによってメンバーの所属が外れた場合は、「退職」の通知は送信されません。

「退職予定日の変更」では、変更日時点ではメンバーに関する情報がすべて空になってしまう場合があるため、例外的に退職日時点の情報を通知します。

例：退職予定日を2023/03/31にした場合、YESOD上の変更日は2023/04/01になりますが、通知には退職日である2023/03/31時点の情報が含まれます。

再入社の取り消しは、選択している通知条件によって通知のされ方が変わります。

選択している通知条件	通知	通知の内容
「メンバー情報変更」のみ	送信される	「メンバー情報変更」（）に変更の詳細が含まれます
「メンバー情報変更」と、ほかの条件	送信される	「メンバー情報変更」（）に変更の詳細が含まれます。ほかの条件の内容は空の配列（）になります（例：入社取り消しの場合はが）
「メンバー情報変更」以外のみ	送信されない	ー

通知には、メンバーの項目のうち、次の条件をすべて満たす項目が含まれます。

条件	内容
項目の対象	メンバーの項目（EntityType: ）
項目の属性	個人・会社・組織・事業所・プロジェクトの属性のいずれか（ReferenceType: / / / / ）
実行ロールの権限	実行ロールで読み取れる（画面レイアウトで表示する設定になっている）項目

また、Webhook通知には作成時に指定した実行ロールの権限が適用されるため、実行ロールで読み取れない項目だけが変更された場合、通知は送信されません。

💡 ポイント 連携先に送りたい項目が通知に含まれない場合は、実行ロールの画面レイアウトで、その項目が表示される設定になっているかを確認してください。

通知先がエラーを返した場合や、応答がない場合は、自動で再試行（リトライ）します。