Public Webhooks：注文・出庫・請求書イベントを自社システムへ送信
Docklify のイベント（注文作成、注文出荷、出庫引渡し、請求書発行、配達完了）を購読し、署名付き HTTPS 送信で自社エンドポイントへリアルタイムに受け取れます。テストイベント、自動リトライ、配信ログ付き。
Public Webhooks は、Docklify で起きた出来事を自社システムへのメッセージに変えます。注文が作成され、出庫が運送業者に引き渡され、請求書が発行された瞬間に、Docklify はあなたが管理するアドレスへ HTTPS 送信を行います。典型的な用途：注文を自社 ERP や会計ソフトへ同期する、自社文面で顧客へ通知する、ダッシュボードへデータを取り込む、API をポーリングせずに後続処理を起動する。
購読できるイベント#
- order.created：受注が作成されたとき（手入力、顧客ポータル、CRM 変換）。
- order.allocated：受注が割り当てられ、在庫が確保されたとき。
- order.fulfilled：受注が完全に出荷されたとき。追跡番号と運送業者を含む。
- order.cancelled：受注がキャンセルされたとき。キャンセル理由コードを含む。
- order.delivered：受注が配達完了とマークされたとき。
- shipment.fulfilled：WMS 出庫伝票が運送業者へ引き渡されたとき。追跡番号を含む。
- receipt.completed：入庫伝票の受入が完了したとき（全明細受入済み）。
- inventory.adjusted：在庫がロケーション上で直接調整されたとき。
- invoice.issued：売掛請求書が生成されたとき。新規請求書は下書きで、状態は status フィールドに表示。
- delivery.completed：ラストマイル配送が受領サインされ完了したとき（配達証明取得済み）。
- test.ping：テストイベント。エンドポイントの疎通と署名検証の確認にいつでも送信可能。
サブスクリプションの作成#
- Integration → Webhooks を開き、「新規サブスクリプション」をクリック。
- 名前：チームが分かる名前を付けます（例：「ERP 同期」）。
- URL：イベントを受け取る自社サーバーの https アドレス。https 必須で、公開アドレスに解決される必要があります。プライベート、LAN、ループバックアドレスは拒否されます。
- イベント：受け取りたいイベントにチェック。後からいつでも変更できます。
- 保存したら、署名シークレットをコピーします（whsec_ で始まります）。サーバーの設定に保存してください。配信が本当に Docklify から来たか検証するために必要です。Webhooks ページでいつでも再表示やローテーションができます。
受信側でやること#
各配信は JSON ボディを持つ HTTPS 送信、つまり封筒（エンベロープ）です。封筒には何が起きたか（type）、いつか（created_at）が入り、詳細は data に入ります：
{
"id": "<event id>",
"type": "order.fulfilled",
"created_at": "2026-10-20T12:00:00.000Z",
"organization_id": "<your organization id>",
"data": {
"order_id": "<order id>",
"order_no": "SO-1001",
"status": "fulfilled",
"tracking_number": "<tracking number>",
"carrier_code": "ups"
}
}- id で重複排除：配信は「少なくとも 1 回」です。自動リトライと手動再送は同じイベント id を再利用するので、処理済み id を記録し、重複はスキップしてください。
- 2xx を返し、速く返すこと：2xx はすべて成功扱いです。配信は 10 秒でタイムアウトします。処理が遅い場合は、先にイベントを保存して 200 を返し、それから処理してください。
- それ以外はすべて失敗扱いです：2xx 以外のステータス、リダイレクト（3xx は追従しません）、タイムアウト、到達不能なアドレス。これらはすべて後述の自動リトライを引き起こします。
署名の検証#
URL を知っている人は誰でも偽のイベントを送信できてしまうため、各配信には署名が付きます。データを信頼する前に署名を検証してください。完全な仕様（ヘッダー名、正確なアルゴリズム、Node と Python の 1 行サンプル）は API ドキュメントの Webhooks セクションにあります。要点：
- 各配信には X-Docklify-Signature ヘッダーが付き、形式は t=<unix 秒>,v1=<hex> です。同じ配信には X-Docklify-Event（イベントタイプ）と X-Docklify-Delivery（配信 id）も付きます。
- v1 は、サブスクリプションの署名シークレットを鍵として、文字列「<t>.<生ボディ>」の HMAC-SHA256 を hex 化したものです。
- 必ず受信したままの生ボディで計算してください。JSON を解析して再シリアライズしてはいけません。空白やキーの順序が変わり、署名が一致しなくなります。
- 署名が一致しない場合は、そのイベントを処理しないでください。
テストイベントの送信#
- Integration → Webhooks でサブスクリプションを開き、「テストイベントを送信」を選択。
- Docklify はすぐにあなたの URL へ test.ping を配信します。テストイベントはどのサブスクリプションにも送信できます（test.ping がイベントリストに含まれることはありません）。
- 配信ログを確認：delivered の行があり、サーバー側で署名検証が通れば、本番イベントの準備完了です。
配信ログとトラブルシューティング#
各配信は配信ログ（Integration → Webhooks → 配信）に記録されます：イベントタイプ、ステータス（pending / delivered / failed）、試行回数、最後の HTTP ステータスコードとエラー、次回リトライ時刻。失敗した配信は 1 分、5 分、30 分、2 時間、6 時間の間隔で自動リトライされ、合計 6 回試行されます。最後の試行後も失敗のままとなり、ログから手動で再送するまで変わりません。再送は同じイベント id を再利用するため、重複排除により安全です。
- アドレス到達不能：サーバーが停止している、URL が間違っている、または名前が公開アドレスに解決されません。エンドポイントを直してから、ログから再送してください。
- 証明書の問題：期限切れや自己署名の TLS 証明書では配信が失敗します。パブリック CA 発行の有効な証明書を使ってください。
- 2xx 以外の応答：受信側がエラーになったか、イベントを拒否しました。ログのコードとエラーを確認し、原因を直してから再送してください。
- タイムアウト：受信側の処理が 10 秒を超えました。先に 2xx を返し、重い処理はバックグラウンドで行ってください。
- 自社側で署名が一致しない：通常はボディの再シリアライズ、またはローテーション後も旧シークレットを使っていることが原因です（上記「署名の検証」参照）。
サブスクリプションの一時停止とシークレットのローテーション#
- 一時停止：Webhooks ページでサブスクリプションを一時停止中に設定します。停止中は新しいイベントは配信されません。いつでも再開できます。エンドポイントのメンテナンス時は一時停止が安全な方法です。
- シークレットのローテーション：シークレットが漏洩した可能性がある、または知っていたチームメンバーが退職した場合は、サブスクリプションページでローテーションしてください。ローテーション後は新しいシークレットでのみ署名されるため、サーバー側も同時に更新してください。旧シークレットのままの受信側は新しい配信を拒否します。