freeeサインは他システムとの連携のためにWebhook機能を提供しています。
例えば「文書の状態変更」に対してWebhook URLを登録しておくことで、文書の状態が変更された場合にfreeeサインからそのURLに対してPOSTリクエストが送られます。
WebhookのリクエストはHTTPの POST メソッドで行われます。
リダイレクトには対応していませんのでご注意ください。
PayloadはJSONで以下の構造を持ちます。
{
"trigger": "<トリガーイベントに応じた文字列>",
<トリガーイベントに応じたデータ>
}
例えば「文書の状態変更」トリガーイベントの場合は以下のようになります。
（見やすいようにフォーマットしていますが、実際のPayloadはフォーマットされていません。）
{
"trigger": "document_status_changed",
"document": {
"id": 1,
"title": "秘密保持文書",
"owner_id": 1,
"status": "draft",
"folder_id": 1,
"created_at": "2020-08-27T16:54:16.522542+09:00",
"updated_at": "2020-08-27T16:54:17.819533+09:00"
}
}
document は状態が変更された文書の情報です。 document の構造の詳細については APIドキュメント
の文書schemaを参照してください。
freeeサインから送られるPOSTリクエストには以下のHTTPヘッダーが付与されています。
| ヘッダー名 | 値の例 | 説明 |
|---|---|---|
| Content-Type | application/json |
application/json 固定です。 |
| X-NinjaSign-RequestId | 290898f2-a7a5-4916-b62d-18b2662a1e01 |
リクエストを一意に識別するためのIDです。 |
| X-NinjaSign-Trigger | document_status_changed |
Payloadの trigger と同じ値が入ります。 |
| X-NinjaSign-Signature | sha256=e9db6ecd84cfd4cd774bead7850447e94bb45239d9ff7ac30a91ab8555b649fe |
不正リクエスト対策の署名です。詳細は後述の「不正リクエスト対策」を参照してください。 |
登録したWebhookに対して、Webhook詳細画面より疎通確認リクエストを送ることができます。
freeeサインからのPOSTリクエストが登録したURLに到達するかどうかの確認にご使用ください。
疎通確認リクエストのPayloadは以下のようになります。
（見やすいようにフォーマットしていますが、実際のPayloadはフォーマットされていません。）
{
"trigger": "post_test",
"message": "webhook test"
}
リクエストヘッダーは通常のPOSTリクエストと同様、前述したものが付与されます。
疎通確認リクエストを含め、Webhookのリクエストの詳細はWebhook詳細画面下部のPOST履歴から確認できます。
リクエストヘッダー、リクエストボディ、レスポンスステータスコード、レスポンスヘッダー、レスポンスボディ等が記録されています。
第三者が偽装した不正なPOSTリクエストに対するセキュリティとして、freeeサインからのPOSTリクエストには署名が付与されています。
署名を検証することでPOSTリクエストがfreeeサインからのものであることを確認できます。
Webhook URLを登録する際、「不正リクエスト対策パスワード」を入力します。
freeeサインはその「不正リクエスト対策パスワード」を使ってPOSTリクエストに署名を行います。
署名はリクエストヘッダーの X-NinjaSign-Signature に格納されています。
X-NinjaSign-Signature の値は以下のような構造になっています。
sha256=<HMAC-SHA256によるハッシュ値>
ハッシュ値は「不正リクエスト対策パスワード」を使ってPayloadから算出されます。
POSTリクエストを受け取った際に、そのPayloadと「不正リクエスト対策パスワード」を使ってハッシュ値を算出し、 X-NinjaSign-Signature のものと一致すればそのリクエストはNINJA
SIGNから送られたものです。
以下にRubyによるハッシュ値算出のサンプルコードを示します。
（ secret は「不正リクエスト対策パスワード」文字列、 payload はPayloadのJSON文字列です。）
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), secret, payload)