- 無料
- ミニマム
- ライト
- フル
- Web
- iPhone
- Android
出来ること
Webhookを使う事で下記のタイミングで通知を受け取る事が出来るようになります。
既にお持ちの基幹システムと在庫連動を従来の公開APIを使った形式よりも素早く低リソースで行う事ができるようになります。
- 在庫の数量が変化した時
設定方法
利用機能設定画面からWebhookの「利用する」をクリックします。
通知先URLに通知を受け取りたいURLを入力します。シークレットキーは後述する送信元の検証の際に利用します。
また、通知先URLの下にある「有効or無効」を有効にすると実際にそのイベントが発生した時に通知先URLに通知されるようになります。とりあえず疎通確認だけを行いたい場合は「無効」の状態で更新してください。
ローカルで開発しているサーバーで受け取りたい
ngrok などのサービスを使って外部公開すると簡単に受け取れます。
疎通確認
Webhookを受け取るサーバーの用意が出来ましたら有効にする前に疎通確認をお願いします。
Webhook設定画面の通知先URLのところにある「テスト」を押すと通知先URLにサンプルのリクエストが送信されます。正しいレスポンスが返ってくれば結果に「正常」と表示されます。不正なレスポンスの場合はエラー内容が表示されますのでエラー内容に沿って修正お願いします。
正常な場合
異常な場合
送信元の検証
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" // 変更日時
}
}その他のイベントについて
もし、この他にも対応すると使い勝手が向上するイベントがありましたらお問い合わせいただけますと幸いです。