会計Webhook概要

Webhookは、複数のWebサービスを連携するための仕組みで、freeeでWebhookを設定すると、次のような操作(通知のキッカケ)が行われたときに、その通知をfreee外部のアプリケーション、システムに通知できます。

  • 各種申請の申請レコード作成
  • 各種申請の申請レコードに対する承認処理
  • 各種申請の申請レコードに対する差戻し処理

例えば、freeeで各種申請で申請レコードの作成があった時、申請が承認されたとき(キッカケ)にSlackやMicrosoft Teams、LINEにメッセージを送る(Webhook通知を処理して他のアプリケーションで通知)ことができます。

この通知、メールではなくてメッセージングツールで飛ばしてほしい、そんな要件を満たすための仕組みです。

また、freeeからの通知をきっかけにfreeeのデータをAPI経由で参照しに行くといったリアクションをとることでAPIコールを効率よく行うことができるようになります。

Webhookを利用するには、freeeと連携するアプリケーションが、Webhookの受信に対応している必要があります。または、Webhookの受信に未対応のWebサービスでも、Zapier、Microsoft Power Automate、IFTTTなどの中継Webサービスを介すことで、freeeと連携できる場合もあります。

会計freeeのWebhookはβ版として提供しています。

β版における制限

以下のようなエラーが発生した場合、Webhook利用アプリでのトラブルシューティングに必要な情報を確認することができません

  • Webhook URLの誤り
  • 上記URLのDNSによる名前解決のエラー
  • 上記URLのサービス側のエラーによる通知失敗
    • サービスのダウン
    • サービスのhttpsポートの異常
  • 上記URLのサービス側のRate Limitによる通信および接続エラー

このページでは、以下の4つについて説明をします。

  • freeeから送信される通知の内容
  • freeeアプリストアでのWebhookの設定手順
  • freeeから通知を受け取るための事前準備と簡易チェックリスト
  • freeeからの通知であることを検証する(任意)

freeeから送信される通知の内容

パラメータ 型・用途 説明
id 文字列 通知ごとに割り当てられる固有のID
application_id 数字 アプリのID
resource 文字列
  • “{Domain}:{Resource}”
      • accounting:approval_request
      • accounting:expense_application
action 文字列
    • created
    • updated
    • destroyed
created_at 文字列 イベントが発生した日次
approval_request: 各種申請 各種申請の作成(action=created)

{

    Id: number,

    company_id: number,

    status: string,

    applicant_id: number

  }

  • approval_request[id]
    • 各種申請のid
  • approval_request[company_id]
    • 各種申請のcompany_id
  • approval_request[status]
    • 各種申請のステータス
      • draft(下書き)
      • in_progress(申請中)
  • approval_request[applicant_id]
    • 各種申請の申請者のユーザーID

各種申請の更新(action=updated)

{

    id: number,

    company_id: number,

    status: string,

    approval_action: string,

    applicant_id: number,

    actor_id: number

}

  • approval_request[id]
    • 各種申請のid
  • approval_request[company_id]
    • 各種申請のcompany_id
  • approval_request[status]
    • 更新後の各種申請のステータス
      • draft(下書き)
      •  in_progress(申請中)
      • approved(承認)
      • rejected(却下)
      • feedback(差戻し)
  • approval_request[approval_action]
    • 各種申請の更新アクション
      • draft(下書きとして保存)
      • apply(申請する)
      • approve(承認する)
      • force_approve(代理承認する)
      • cancel(申請を取り消す)
      • reject(却下する)
      • feedback(差戻し)
      • force_feedback(承認済み・却下済みを取り消す)
  • approval_request[applicant_id]
    • 各種申請の申請者のuser_id
  • approval_request[actor_id]
    • 各種申請の更新を行ったユーザーのid

 

freeeアプリストア>アプリ管理で行うWebhookの設定手順

freeeアプリストアの開発者ページ右上の表記が変わるので、[アプリ管理]をクリックします。

既に作成済みのアプリがオレンジ枠部分に表示されます。新規作成する場合は赤枠[新規追加]をクリックします。

 

アプリ詳細ページに遷移して[Webhook設定]タブをクリックし、Webhookの利用に必要となる各項目の値を入力します。

    • Webhook設定
      • Webhookを利用する場合は、有効。利用しない場合は、無効にしてください。
    • Webhook URL
      • Webhookの通知を受け取るURLを入力してください。https以外のプロトコルは利用できません。正しくない値を入れていると通知が届かないため、指定しているURLが正しいことを確認してください。
    • 通知を送信する条件
      • Webhookの通知を飛ばず条件(トリガー)をチェックしてください。

[下書き保存]をクリックします。

freeeからの通知を受け取るための事前準備と簡易チェックリスト

Webhook通知を受けるにあたり、ユーザーが事前に利用予定のアプリを認可(どのリソースにアクセスできるかの確認と承認)している必要があります。ユーザーにより認可されていないアプリにはfreeeはWebhookの送信を行いません。

番号 簡易チェック内容
1 freeeアプリストアでアプリ毎のWebhook設定ができている

  • ”有効”に設定できているか
  • URLは正しいか
  • 通知を送信する条件は正しいか
2 Webhookを受信するアプリケーションはWebhookによる通知機能を利用したいアプリケーションユーザーにより認可を受けているか
3 上記ユーザーの所属するfreeeの事業所が認可時に選択されているか

(該当事業所に所属する任意のユーザーのアクションをトリガーにWebhook送信)

Webhookの通知を受け取るためには事業所がアプリと連携している必要があります。事業所と連携しているアプリはfreeeアプリストアのマイアプリで確認できます。

作成したアプリが事業所と連携されていない場合は、一度アクセストークンを取得することにより事業所とアプリが連携されます。

    • アプリの詳細画面の「基本情報」タブを開きます。

 

ページ下に「モバイル・JSアプリ認証用URL」が表示されているので、そのURLを開きます。  

 

アプリ連携ページが表示されるので、連携を許可します。

なお、ここで取得したアクセストークンは事業所とアプリの連携をして通知を受け取るために必要な操作の中で必要となったもので、Webhookの通知受け取りには使用しません。最後にマイアプリに移動し、アプリが連携されていることを確認します。

Webhookの通知がfreeeから送信されたものか検証する

  • 検証とチェックは任意ですが、freeeからの通知であることを確かめることができる手段です。
  • Webhookの通知が、freeeから送信されたものかを検証するために、検証用トークンが使えます。
  • 検証用トークンは、「Webhook設定」タブのページに表示されます。値は、アプリ毎にユニークな文字列です。

 

  • この検証用トークンが、Webhookのリクエストヘッダー ”X-freee-token”にある値と一致することを確認してください。一致する場合は、そのWebhookの通知がfreeeから送信されたものであることになります。