- 無料
- ミニマム
- ライト
- pro
- フル
- Web
- iPhone
- Android
出来ること
Webhookを使う事で下記のタイミングで通知を受け取る事が出来るようになります。
- 在庫の数量が変化した時
- 在庫データが変化した時
- 入庫データのステータスが変化した時（新規作成時も含む）
- 出庫データのステータスが変化した時（新規作成時も含む）
既にお持ちの基幹システムと在庫連動を従来の公開APIを使った形式よりも素早く低リソースで行う事ができるようになります。
設定方法
利用機能設定画面からWebhookの「利用する」をクリックします。
通知先URLに通知を受け取りたいURLを入力してください。
※シークレットトークンは後述する送信元の検証の際に利用します。
横にある「テスト」ボタンを押して、データが正常に届くことを確認してください。
※ローカルで開発しているサーバーで通知を受け取りたい場合、ngrok などのサービスを使ってサーバーを外部公開すると簡単に受け取れるので便利です。
送信元の検証
Webhookの送信元がzaicoかどうかを検証していただく方法としてリクエストヘッダーに送っている「x-zaico-signature-256」の値が一致するかというのがあります。
Rubyの場合はこのような形になります。
def verify_signature(payload_body)
signature = 'sha256=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['SECRET_TOKEN'], payload_body)
return halt 500, "Invalid signature" unless Rack::Utils.secure_compare(signature, request.env['HTTP_X_zaico_SIGNATURE_256'])
endzaicoではIPアドレスのご提供は行っておりませんので送信元の検証については上記のヘッダーをご利用ください。
シークレットトークンの再生成
Webhook設定画面からシークレットトークンの再生成が可能です。
再生成後のイベントについては新しいシークレットトークンでsignatureが計算されますが送信途中、再送中のイベントに関しては生成前のシークレットトークンで計算したsignatureで送られますので既に稼働しているサービスでシークレットトークンを再生成する場合には一時的に古いsignatureでも検証することを推奨します。
レスポンス
正常かどうか判断するデータはレスポンスのステータスコードが意図したものかどうかになります。
- 2xx：正常
- それ以外：異常
異常の場合は一定間隔でリトライしますので仮に処理すべきではないデータの場合にも 2xx のステータスコードを返すようにしてください。
タイムアウト
Webhookの通知を受けたら1秒以内にレスポンスを返してください。
1秒以内にレスポンスを返せない場合、異常と判断され再送されます。
再送間隔・期間
- 間隔：約1分
- 期間：1日
間隔、期間については予告なく変更される可能性があります。
通知順序
通知されるイベントの順序は実際のイベントの順序とは異なる場合があります。
処理の冪等性
同じイベントが1回以上届く可能性があるためイベントを受け取った時の処理は冪等にすることをおすすめします。
共通のリクエストヘッダー
Webhook時には共通して下記のヘッダーが送信されます。
- user-agent：ZaicoWebhook/1.0
- content-type：application/json
- x-zaico-company-id：事業所ID（例：123456）
- x-zaico-event：イベント種別（例：changed_quantity）
- x-request-id：リクエスト毎のID（例：432dc9c5-7d14-49e7-8199-05c2a76fddd3）
- x-zaico-signature-256：ペイロードをシークレットトークンを使って算出したSHA256の値（例：sha256=43bb5cf48442edfd14d6d97fa81cb563569e4992666bf75730334477f473e5ff）
各種イベント毎のペイロード
在庫の数量が変化した時（changed_quantity）
{
"inventory": {
"id": 49375, // 在庫ID
"code": "1413790e-fc3c-4fa7-aed4-6b6eed9a6e03", // QRコード
"title": "Julienne Macejkovic", // 物品名
"quantity": "150.0", // 変更後の数量
"updated_at": "2021-10-02T22:44:15+09:00" // 変更日時
}
}在庫データが変化した時（changed_inventory）
{
"inventory_id": 123, // 在庫ID
"changed_attributes": ["title", "quantity"], //標準項目で変更された項目一覧
"changed_optional_attributes": ["納品単価", "型式"], // 追加項目で変更された項目一覧
"updated_at": "2024-11-08T16:26:54.493728+09:00" // 変更日時
}入庫データのステータスが変化した時（changed_purchase_status）
{
"purchase": {
"id": 210948,
"num": "119",
"customer_name": "田村商社",
"create_user_name": "[stg]スナ開発_488",
"issue_date": null,
"purchase_date": null,
"status": "ordered",
"etc": "発注書備考です",
"created_at": "2024-06-03T10:58:46+09:00",
"updated_at": "2024-06-04T15:49:02+09:00",
"earliest_estimated_purchase_date": "2024-06-08T00:00:00+09:00",
"memo": "入庫メモです",
"user_group": "基本グループ,管理者,新しいユーザーグループ"
}
}出庫データのステータスが変化した時（changed_packing_slip_status）
{
"packing_slip": {
"id": 210472,
"created_at": "2024-05-28T15:07:38+09:00",
"updated_at": "2024-06-04T15:50:26+09:00",
"date_of_issue": null,
"create_user_name": "[stg]スナ開発_488",
"customer_name": "田村商社",
"customer_name_postfix": null,
"num": "256",
"delivery_date": "2024-06-04T00:00:00+09:00",
"status": "completed_delivery",
"earliest_estimated_delivery_date": null,
"memo": "出庫メモです",
"note": "納品書備考です",
"user_group": "基本グループ,管理者,新しいユーザーグループ"
}
}在庫データが変化した時のwebhookについて
通知の条件
在庫データが変化した時のwebhookは下記の項目を変更したとき通知されます。論理在庫数や何も変更されずに保存し直しされた場合などは通知されません。
-
追加項目（入庫単価・出庫単価含む）
-
物品名
-
数量（実在庫）
-
単位
-
カテゴリ
-
状態
-
QRコード・バーコードの値
-
備考
-
グループタグ
- ユーザーグループ
-
保管場所
また、新規作成、削除/復元された際は通知されません。
なお、変更したときに通知される項目は将来予告なく追加されますので、変更したときに通知される項目が増えても問題のないシステム連携をお願いいたします。
changed_attributesの値
"changed_attributes"の値の配列には下記項目が入る可能性があります。
-
物品名：title
-
数量（実在庫）：quantity
-
単位：unit
-
カテゴリ：category
-
状態：state
-
QRコード・バーコードの値：code
-
備考：etc
-
グループタグ：group_tag
- ユーザーグループ：user_group
-
保管場所：place
その他のイベントについて
もし、この他にも対応すると使い勝手が向上するイベントがありましたらお問い合わせいただけますと幸いです。