Webhookは、複数のWebサービスを連携するための仕組みです。freeeでWebhookを設定すると、次のような操作(通知のキッカケ)が行われたときにその通知をfreee外部のアプリケーション、システムに通知できます。
- 経費精算、各種申請、支払依頼の申請レコード作成
- 経費精算、各種申請、支払依頼の申請レコードに対する承認処理
- 経費精算、各種申請、支払依頼の申請レコードに対する差戻し処理
例えば、freeeで各種申請で申請レコードの作成があった時、申請が承認されたとき(キッカケ)にSlackやMicrosoft Teams、LINEにメッセージを送る(Webhook通知を処理して他のアプリケーションで通知)ことができます。
この通知、メールではなくてメッセージングツールで飛ばしてほしい、そんな要件を満たすための仕組みです。
また、freeeからの通知をきっかけにfreeeのデータをAPI経由で参照しに行くといったリアクションをとることでAPIコールを効率よく行うことができるようになります。具体的な使い方のポイントは会計Webhook活用ポイント紹介(会計ワークフロー編)を参照してください。
Webhookを利用するには、freeeと連携するアプリケーションが、Webhookの受信に対応している必要があります。または、Webhookの受信に未対応のWebサービスでも、Zapier、Microsoft Power Automate、IFTTTなどの中継Webサービスを介すことで、freeeと連携できる場合もあります。
freee会計のWebhookはβ版として提供しています。
β版における制限以下のようなエラーが発生した場合、Webhook利用アプリでのトラブルシューティングに必要な情報を確認することができません
|
このページでは、以下の4つについて説明をします。
- freeeから送信される通知の内容
- freeeアプリストアでのWebhookの設定手順
- freeeから通知を受け取るための事前準備と簡易チェックリスト
- freeeからの通知であることを検証する(任意)
freeeから送信される通知の内容
共通プロパティ
以下のプロパティはすべてのWebhookイベントオブジェクトに含まれます
パラメータ | 型・用途 | 説明 |
id | 文字列 |
|
application_id | 数字 | アプリのID |
resource | 文字列 |
|
action | 文字列 |
|
created_at | 文字列 | イベントが発生した日次 |
各種申請
各種申請に関するWebhookイベントオブジェクトです。共通プロパティに加え、以下のプロパティが追加されます。
パラメータ | 型・用途 | 説明 | |
approval_request | 各種申請の作成(action=created) |
|
|
approval_request | 各種申請の更新(action=updated) |
|
経費精算
経費精算に関するWebhookイベントオブジェクトです。共通プロパティに加え、以下のプロパティが追加されます。
パラメータ | 型・用途 | 説明 | |
---|---|---|---|
expense_application | 経費精算の作成(action=created) |
|
|
expense_application | 経費精算の更新(action=updated) |
|
支払依頼
支払依頼に関するWebhookイベントオブジェクトです。共通プロパティに加え、以下のプロパティが追加されます。
支払依頼の更新の場合において、payment_request[status]が以下の2つに当てはまる場合、通知を行いません。
- 更新前のステータスが申請中、更新後のステータスが申請中
- 更新前のステータスが差戻し、更新後のステータスが差戻し
パラメータ | 型・用途 | 説明 | |
---|---|---|---|
payment_request | 支払依頼の作成(action=created) |
|
|
payment_request | 支払依頼の更新(action=updated) |
|
freeeアプリストア>アプリ管理で行うWebhookの設定手順
freeeアプリストアの開発者ページ右上の表記が変わるので、[アプリ管理]をクリックします。
既に作成済みのアプリがオレンジ枠部分に表示されます。新規作成する場合は赤枠[新規追加]をクリックします。
アプリ詳細ページに遷移して[Webhook設定]タブをクリックし、Webhookの利用に必要となる各項目の値を入力します。
-
- Webhook設定
- Webhookを利用する場合は、有効。利用しない場合は、無効にしてください。
- Webhook URL
- Webhookの通知を受け取るURLを入力してください。https以外のプロトコルは利用できません。正しくない値を入れていると通知が届かないため、指定しているURLが正しいことを確認してください。
- 通知を送信する条件
- Webhookの通知を飛ばず条件(トリガー)をチェックしてください。
- Webhook設定
[下書き保存]をクリックします。
freeeからの通知を受け取るための事前準備と簡易チェックリスト
Webhook通知を受けるにあたり、ユーザーが事前に利用予定のアプリを認可(どのリソースにアクセスできるかの確認と承認)している必要があります。ユーザーにより認可されていないアプリにはfreeeはWebhookの送信を行いません。
番号 | 簡易チェック内容 |
1 | freeeアプリストアでアプリ毎のWebhook設定ができている
|
2 | Webhookを受信するアプリケーションはWebhookによる通知機能を利用したいアプリケーションユーザーにより認可を受けているか |
3 | 上記ユーザーの所属するfreeeの事業所が認可時に選択されているか
(該当事業所に所属する任意のユーザーのアクションをトリガーにWebhook送信) |
Webhookの通知を受け取るためには事業所がアプリと連携している必要があります。事業所と連携しているアプリはfreeeアプリストアのマイアプリで確認できます。
作成したアプリが事業所と連携されていない場合は、一度アクセストークンを取得することにより事業所とアプリが連携されます。
-
- アプリの詳細画面の「基本情報」タブを開きます。
ページ下に「モバイル・JSアプリ認証用URL」が表示されているので、そのURLを開きます。
アプリ連携ページが表示されるので、連携を許可します。
なお、ここで取得したアクセストークンは事業所とアプリの連携をして通知を受け取るために必要な操作の中で必要となったもので、Webhookの通知受け取りには使用しません。最後にマイアプリに移動し、アプリが連携されていることを確認します。
Webhookの通知がfreeeから送信されたものか検証する
- 検証とチェックは任意ですが、freeeからの通知であることを確かめることができる手段です。
- Webhookの通知が、freeeから送信されたものかを検証するために、検証用トークンが使えます。
- 検証用トークンは、「Webhook設定」タブのページに表示されます。値は、アプリ毎にユニークな文字列です。
- この検証用トークンが、Webhookのリクエストヘッダー ”x-freee-token”にある値と一致することを確認してください。一致する場合は、そのWebhookの通知がfreeeから送信されたものであることになります。