digiwin_dsp 0.2.4 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feebd7c9c5d89e9d6306b00ecccb402151c9e299201ecf3b98cfbf7c9a1590a1
-  data.tar.gz: 7c9fbb5aa913649c417a4f23caf6bf9f3b10bc92b6c2efb34e9cc1cdce8808ad
+  metadata.gz: 3cfde42cbd2b4448e9c5e4927e9ecb65f61ae19a46474154ae1349d73cd2461c
+  data.tar.gz: 6d35ad2fd9430c5440f626b15f3c98c9a8dd627c2732bb349bc355f6693d9de3
 SHA512:
-  metadata.gz: 292e2d148f9af342959a826cbed33999cbd81b169719fa79882b309bfdfb6b1800e88ed18dfcd3d0210784d85f7df9dea1e02e63b0a0f9e67e276e235c7c403d
-  data.tar.gz: 437cd4412d96aa9914b99cea75ca5ce06274870aada7a2462b53d64e18eb5ebb03b9dbee07bd78cadab08880652aabe49e7ce88ff987c043be7530ff031c3712
+  metadata.gz: 95d2787c766fa0a316542b37d0b5620738e9dcff687562875698e5c1d0f3a3ffaaa2e93a81f24b34e0f6e27047a9c53d22e1368725879f36a6f48116b02f2b7c
+  data.tar.gz: c8f1b7781c06e3fa745d4e2a6770d7442dd443a38e10ca4ce6767b5aaa82bbf1016ef8aeb961922ebe9f41321d6702be561a1c82810223335a0a340c6f6eb27b

data/CHANGELOG.md

@@ -6,6 +6,53 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-06-12
+
+Hardening patch from a full gem + docs review. All fixes grounded in the vendor YAML specs.
+
+### Fixed
+
+- **TLS failures now raise `DigiwinDsp::NetworkError`.** `Faraday::SSLError` sits directly under `Faraday::Error` (not `ConnectionFailed`), so certificate problems previously leaked as raw Faraday exceptions that `rescue DigiwinDsp::Error` could not catch.
+- **Three more DSP failure messages classify into typed exceptions** instead of falling through to generic `Error`:
+  - `Shipped:訂單已出貨，不可取消` (DSPOOFFICIAL002) → `ValidationError` — permanent; the order left the warehouse
+  - `Processing:新增訂單處理中，不可取消` (DSPOOFFICIAL002) → `RateLimitError` — retryable once ERP processes the add
+  - `SalesNotCreate:銷貨單未成立` (DSPOOFFICIAL004) → `RateLimitError` — retryable once ERP converts the sales doc
+  Sidekiq/ActiveJob retry strategies can now distinguish "don't retry" from "retry later" on cancel and invoice flows.
+- **`Webhooks::Event.parse_json` / `.extract_request` are now private class methods.** They were internal helpers accidentally exposed on all three event classes.
+- **`WebhookSubscription` rejects non-`https://` callback addresses** at registration time. DSPOOFFICIAL100 mandates HTTPS callbacks, and with no HMAC signing a plaintext callback would be indefensible. (Previously the README claimed this was enforced when it wasn't.)
+
+### Docs
+
+- `dsp-api-spec.md`: corrected the e-invoice carrier field name — `Resources::Invoice` sends **`carrier_type`** (DSPOOFFICIAL004:164), not `carrier_code`. `carrier_code` is only on `Resources::Order` and the inbound webhook. Optional fields aren't validated client-side, so the wrong name silently drops carrier data.
+- `dsp-api-spec.md`: failure-message table now covers 002 (cancel) and 004 (invoice) sources, not just 001.
+- README: webhook security bullet now describes the actual https enforcement.
+
+## [0.3.0] - 2026-05-28
+
+DSP webhook support (DSPOOFFICIAL100). Lets a Rails app register a callback URL with DSP, then receive and parse the three documented ERP-originated push events: inventory updates, shipping/logistics status, and invoice issuance.
+
+### Added
+
+- **`DigiwinDsp::Resources::WebhookSubscription`** — outbound wrapper for `POST /v1/webhook` on the new webhook base path. Registers a callback URL for one of three actions (`product/inventory_update` / `wms/logistics/package/update` / `invoice/update`). Validates locally: known action, non-empty address, ≤500 chars per the spec.
+- **`DigiwinDsp::Webhooks` module** with three inbound event parsers:
+  - `Webhooks::InventoryUpdate` — exposes `prod`, `platform_id`, `sale_page_id`, `spec_list`
+  - `Webhooks::LogisticsUpdate` — exposes `form_no`, `func_name`, `status_date`, `status_time`, `tracking_number`, `distributor_code`, `message`
+  - `Webhooks::InvoiceUpdate` — exposes `invoices` (Array; DSP batches multiple invoices per push)
+  - `Webhooks.parse(raw_body, action:)` dispatcher routes by action string
+  - `Webhooks::ParseError < ValidationError` for malformed JSON / envelope / unknown action
+- **`Configuration#webhook_base_url`** — separate base path for DSPOOFFICIAL100 (`/api/webhook` vs the SalesOrder `/api/DSP`). Defaults resolve from `environment`; explicit override via `DIGIWIN_DSP_WEBHOOK_BASE_URL` env var. Same HTTPS + `allowed_hosts` guard as `base_url`.
+- **Client `base_url:` kwarg override** so the new `WebhookSubscription` can target the webhook base path without leaking the routing into `Configuration#base_url`.
+- **Dual-envelope detection in `Client#inspect_envelope`** — handles both `{Status, Message, response_detail[]}` (SalesOrder family) and `{srvver, std_data: {execution, response}}` (webhook family). Both run through the same `ENVELOPE_FAILURE_MAP` regex classifier, so `WrongStatus:`, `系統異常:`, `Duplicated:`, etc. produce the right typed exception regardless of endpoint.
+- `docs/dsp-specs/DSPOOFFICIAL100.yaml` — the OpenAPI spec used to drive the implementation.
+
+### Security
+
+- ⚠️ **DSP does not sign inbound webhooks.** No HMAC header documented. README calls out defense-in-depth: HTTPS-only callback URL, unguessable path, optional IP allowlist, 200-within-30s reply, caller-side idempotency by `form_no` / `invoice_number`.
+
+### Changed
+
+- Removed dead `Client#envelope_error_attrs` helper (replaced by `classify_envelope_failure` which serves both envelope shapes).
+
 ## [0.2.4] - 2026-05-22
 
 ### Added
@@ -179,7 +226,9 @@ Initial release. Covers the four Self-hosted Website Module (自有官網模組)
 - The gem is **synchronous on purpose**. Callers wrap requests in their own background job runner (e.g. ActiveJob) when needed.
 - Idempotency: clients can send `X-Idempotency-Key` via the `idempotency_key:` kwarg. DSP also dedupes server-side by `form_no + platform_id`.
 
-[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.4...HEAD
+[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/7a6163/digiwin_dsp/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.4...v0.3.0
 [0.2.4]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/7a6163/digiwin_dsp/compare/v0.2.1...v0.2.2

data/README.md

@@ -13,6 +13,8 @@ Ruby client for the Digiwin DSP Self-hosted Website Module (自有官網模組)
 | Cancel order | `DigiwinDsp::Resources::Cancellation` | `POST /v1/SalesOrder/cancel` |
 | Invoice update | `DigiwinDsp::Resources::Invoice` | `POST /v1/SalesOrder/invoice` |
 | Return | `DigiwinDsp::Resources::Return` | `POST /v1/SalesOrder/return` |
+| Register webhook | `DigiwinDsp::Resources::WebhookSubscription` | `POST /v1/webhook` (on webhook_base_url) |
+| Receive webhook (inbound) | `DigiwinDsp::Webhooks.parse` | — |
 
 See [`docs/dsp-api-spec.md`](./docs/dsp-api-spec.md) (plus `docs/dsp-specs/*.yaml`) for the wire spec.
 
@@ -53,6 +55,7 @@ Every setting also falls back to an ENV var:
 | `platform_id` | `DIGIWIN_DSP_PLATFORM_ID` | `nil` | sent **per-record** in `request_detail.platform_id` (not in auth headers) |
 | `environment` | `DIGIWIN_DSP_ENV` | `:sandbox` | `:sandbox` (UAT) or `:production` |
 | `base_url` | `DIGIWIN_DSP_BASE_URL` | resolved from `environment` | must be `https://` and have a host in `allowed_hosts` |
+| `webhook_base_url` | `DIGIWIN_DSP_WEBHOOK_BASE_URL` | resolved from `environment` | for `WebhookSubscription`; same validation as `base_url` |
 | `allowed_hosts` | — | `["digiwindsp.digiwin.com"]` | SSRF allowlist; extend if you proxy DSP through a different domain |
 | `timeout` | — | `10` | seconds |
 | `open_timeout` | — | `5` | seconds |
@@ -154,12 +157,68 @@ Each endpoint requires a specific `order_status` value inside `request_detail`.
 
 ### Idempotency
 
-Pass `idempotency_key:` to attach an `X-Idempotency-Key` request header. DSP also dedupes server-side by `form_no + platform_id` and returns `Duplicated:訂單不可重複` on a re-send (mapped to `DuplicateRequestError`).
+**DSP only dedupes on `form_no + platform_id`.** Use a deterministic `form_no` derived from your domain order ID and DSP will reject duplicates with `Duplicated:訂單不可重複` (mapped to `DuplicateRequestError`).
+
+The `idempotency_key:` kwarg attaches an `X-Idempotency-Key` request header for logging/tracing on your side, but **DSP UAT does not act on it** (live-verified 2026-05-22 with two distinct `form_no` POSTs sharing the same key — both succeeded). Treat the header as a trace ID, not an idempotency guarantee.
 
 ```ruby
 DigiwinDsp::Resources::Order.create(record, idempotency_key: "order-#{record['form_no']}")
 ```
 
+### Webhooks (DSP push events)
+
+Two halves — register a callback URL with DSP, then receive ERP-originated events at that URL.
+
+**Register (outbound)** — tell DSP where to push notifications for one of three documented actions:
+
+```ruby
+DigiwinDsp::Resources::WebhookSubscription.create(
+  action:  "product/inventory_update",         # or "wms/logistics/package/update", "invoice/update"
+  address: "https://yourshop.example.com/webhooks/dsp/inventory"
+)
+# => { "platform_id" => ..., "address" => ..., "action" => ... }
+```
+
+`platform_id` falls back to `Configuration#platform_id`; `prod` defaults to `"OFFICIALWEBSITE"`. Each action needs its own subscription call.
+
+**Receive (inbound)** — parse what DSP POSTs to your callback URL:
+
+```ruby
+# config/routes.rb
+post "/webhooks/dsp/inventory", to: "dsp_webhooks#inventory"
+
+# app/controllers/dsp_webhooks_controller.rb
+class DspWebhooksController < ActionController::API
+  def inventory
+    event = DigiwinDsp::Webhooks::InventoryUpdate.parse(request.raw_post)
+    # event.platform_id, event.sale_page_id, event.spec_list[] — see docs/dsp-specs/DSPOOFFICIAL100.yaml
+    DspInventoryUpdateJob.perform_later(event.raw)
+    head :ok
+  rescue DigiwinDsp::Webhooks::ParseError => e
+    Rails.logger.error("DSP webhook parse failed: #{e.dsp_message || e.message}")
+    head :bad_request
+  end
+end
+```
+
+Or use the dispatcher when one URL handles all 3 actions:
+
+```ruby
+event = DigiwinDsp::Webhooks.parse(request.raw_post, action: params[:action])
+case event
+when DigiwinDsp::Webhooks::InventoryUpdate then ...
+when DigiwinDsp::Webhooks::LogisticsUpdate then event.tracking_number
+when DigiwinDsp::Webhooks::InvoiceUpdate   then event.invoices.each { |inv| ... }
+end
+```
+
+> ⚠️ **DSP does NOT sign inbound webhooks.** There is no HMAC header. Defend the callback endpoint with:
+> - HTTPS-only — `WebhookSubscription` rejects non-`https://` addresses at registration time (DSP's own spec mandates HTTPS callbacks)
+> - An unguessable URL path (treat it as a secret)
+> - An IP allowlist for DSP's egress range if your network team can get one
+> - Replying `200 OK` within 30 seconds (DSP will retry and may eventually block your endpoint if too many calls fail)
+> - **Idempotency by `form_no` / `invoice_number` / etc. on your side** — DSP may retry the same event
+
 ### Background jobs
 
 The gem is synchronous on purpose. Wrap calls in your own job runner:

data/lib/digiwin_dsp/client.rb

@@ -33,13 +33,17 @@ module DigiwinDsp
       [/Duplicated:/, DuplicateRequestError], # order already exists
       [/Processing:資料處理中/, RateLimitError], # transient; retry later
       [/Processing:取消訂單處理中/, ValidationError], # cancel in flight
+      [/Processing:新增訂單處理中/, RateLimitError], # add in flight; cancel retryable after ERP processes (002)
+      [/Shipped:/, ValidationError], # already shipped — cancel permanently impossible (002)
+      [/SalesNotCreate:/, RateLimitError], # ERP hasn't converted sales doc yet; invoice retryable (004)
       [/WrongStatus:/, ValidationError], # bad payload
       [/系統異常:/, ServerError] # DSP internal error
     ].freeze
 
-    def initialize(configuration: DigiwinDsp.configuration, authenticator: nil)
-      @configuration = configuration
-      @authenticator = authenticator || Authenticator.new(configuration)
+    def initialize(configuration: DigiwinDsp.configuration, authenticator: nil, base_url: nil)
+      @configuration     = configuration
+      @authenticator     = authenticator || Authenticator.new(configuration)
+      @base_url_override = base_url
     end
 
     def post(path, body, idempotency_key: nil, headers: {})
@@ -51,7 +55,10 @@ module DigiwinDsp
         req.body = body
       end
       handle_response(response)
-    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => e
+      # SSLError sits directly under Faraday::Error (not ConnectionFailed),
+      # so it needs an explicit entry — otherwise TLS failures leak as raw
+      # Faraday exceptions that `rescue DigiwinDsp::Error` won't catch.
       raise NetworkError, e.message
     end
 
@@ -78,7 +85,7 @@ module DigiwinDsp
     end
 
     def connection_base_url
-      base = @configuration.base_url
+      base = @base_url_override || @configuration.base_url
       base.end_with?("/") ? base : "#{base}/"
     end
 
@@ -108,11 +115,31 @@ module DigiwinDsp
     end
 
     def inspect_envelope(body)
-      return body unless body.is_a?(Hash) && body["Status"].to_s.casecmp("failure").zero?
+      return body unless body.is_a?(Hash)
 
-      message = body["Message"].to_s
+      failure = detect_envelope_failure(body)
+      return body unless failure
+
+      raise classify_envelope_failure(failure[:message], code: failure[:code], body: body)
+    end
+
+    # Detects either envelope shape and returns {message, code} if it's a
+    # failure response, or nil if it's a success / non-envelope body.
+    # - DSPOOFFICIAL100: { srvver, std_data: { execution: { code, description }, response } }
+    # - DSPOOFFICIAL001-005: { Status, Message, response_detail }
+    def detect_envelope_failure(body)
+      if (exec = body.dig("std_data", "execution"))
+        return nil if exec["code"].to_s == "0"
+
+        { message: exec["description"].to_s, code: exec["code"] }
+      elsif body["Status"].to_s.casecmp("failure").zero?
+        { message: body["Message"].to_s, code: body["Status"] }
+      end
+    end
+
+    def classify_envelope_failure(message, code:, body:)
       klass = ENVELOPE_FAILURE_MAP.find { |regex, _| regex.match?(message) }&.last || Error
-      raise klass.new(message, **envelope_error_attrs(body))
+      klass.new(message, code: code, dsp_message: message, request_id: body["request_id"], http_status: 200)
     end
 
     def http_message(status, body)
@@ -130,15 +157,6 @@ module DigiwinDsp
       }
     end
 
-    def envelope_error_attrs(body)
-      {
-        code: body["Status"],
-        dsp_message: body["Message"],
-        request_id: body["request_id"],
-        http_status: 200
-      }
-    end
-
     # Block CRLF/LF/CR in header names and values. RFC 7230 §3.2.4 forbids
     # them and Faraday + Net::HTTP catch many forms, but not all — close
     # the gap to prevent header-injection / request-smuggling.

data/lib/digiwin_dsp/configuration.rb

@@ -14,20 +14,28 @@ module DigiwinDsp
       production: "https://digiwindsp.digiwin.com/DSP/api/DSP"
     }.freeze
 
+    # Webhook-subscription endpoint (DSPOOFFICIAL100) lives at a separate
+    # base path from the SalesOrder endpoints.
+    WEBHOOK_BASE_URLS = {
+      sandbox: "https://digiwindsp.digiwin.com/DSP_UAT/api/webhook",
+      production: "https://digiwindsp.digiwin.com/DSP/api/webhook"
+    }.freeze
+
     attr_accessor :api_key, :api_secret, :platform_id, :environment, :logger,
                   :timeout, :open_timeout, :allowed_hosts
-    attr_writer :base_url
+    attr_writer :base_url, :webhook_base_url
 
     def initialize
-      @api_key       = ENV["DIGIWIN_DSP_API_KEY"]
-      @api_secret    = ENV["DIGIWIN_DSP_API_SECRET"]
-      @platform_id   = ENV["DIGIWIN_DSP_PLATFORM_ID"]
-      @environment   = ENV.fetch("DIGIWIN_DSP_ENV") { "sandbox" }.to_sym
-      @base_url      = ENV["DIGIWIN_DSP_BASE_URL"]
-      @timeout       = DEFAULT_TIMEOUT
-      @open_timeout  = DEFAULT_OPEN_TIMEOUT
-      @logger        = Logger.new(IO::NULL)
-      @allowed_hosts = DEFAULT_ALLOWED_HOSTS.dup
+      @api_key           = ENV["DIGIWIN_DSP_API_KEY"]
+      @api_secret        = ENV["DIGIWIN_DSP_API_SECRET"]
+      @platform_id       = ENV["DIGIWIN_DSP_PLATFORM_ID"]
+      @environment       = ENV.fetch("DIGIWIN_DSP_ENV") { "sandbox" }.to_sym
+      @base_url          = ENV["DIGIWIN_DSP_BASE_URL"]
+      @webhook_base_url  = ENV["DIGIWIN_DSP_WEBHOOK_BASE_URL"]
+      @timeout           = DEFAULT_TIMEOUT
+      @open_timeout      = DEFAULT_OPEN_TIMEOUT
+      @logger            = Logger.new(IO::NULL)
+      @allowed_hosts     = DEFAULT_ALLOWED_HOSTS.dup
     end
 
     def base_url
@@ -36,6 +44,12 @@ module DigiwinDsp
       url
     end
 
+    def webhook_base_url
+      url = @webhook_base_url || resolve_default_webhook_base_url
+      validate_url!(url)
+      url
+    end
+
     def validate!
       return unless api_key.nil? || api_key.to_s.empty?
 
@@ -52,6 +66,13 @@ module DigiwinDsp
       end
     end
 
+    def resolve_default_webhook_base_url
+      WEBHOOK_BASE_URLS.fetch(environment) do
+        raise ConfigurationError,
+              "unknown environment #{environment.inspect}; expected one of #{WEBHOOK_BASE_URLS.keys.inspect}"
+      end
+    end
+
     def validate_url!(url)
       uri = URI.parse(url)
       raise ConfigurationError, "base_url must use https (got #{uri.scheme.inspect})" unless uri.scheme == "https"

data/lib/digiwin_dsp/resources/webhook_subscription.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Resources
+    # Registers a webhook callback URL with DSP (DSPOOFFICIAL100,
+    # POST /v1/webhook on the webhook_base_url).
+    #
+    # Not a Resources::Base subclass — the request envelope is a single
+    # `request` object (not `request_detail[]` array), the fields are
+    # explicit kwargs (not an arbitrary hash), and it targets the
+    # webhook_base_url instead of base_url.
+    class WebhookSubscription
+      PATH = "/v1/webhook"
+      DEFAULT_PROD = "OFFICIALWEBSITE"
+      ACTIONS = %w[
+        product/inventory_update
+        wms/logistics/package/update
+        invoice/update
+      ].freeze
+      ADDRESS_MAX_LENGTH = 500
+
+      def self.create(action:, address:, platform_id: nil, prod: DEFAULT_PROD)
+        new.create(action: action, address: address, platform_id: platform_id, prod: prod)
+      end
+
+      def initialize(client = nil)
+        @client = client || Client.new(base_url: DigiwinDsp.configuration.webhook_base_url)
+      end
+
+      def create(action:, address:, platform_id: nil, prod: DEFAULT_PROD)
+        validate_args!(action: action, address: address)
+        body = build_body(action: action, address: address, platform_id: platform_id, prod: prod)
+        response = @client.post(PATH, body)
+        response.dig("std_data", "response") ||
+          raise(DigiwinDsp::ServerError, "DSP returned execution.code=0 without std_data.response")
+      end
+
+      private
+
+      def validate_args!(action:, address:)
+        unless ACTIONS.include?(action)
+          raise DigiwinDsp::ValidationError,
+                "action must be one of #{ACTIONS.inspect} (got #{action.inspect})"
+        end
+        raise DigiwinDsp::ValidationError, "address is required" if address.nil? || address.to_s.empty?
+
+        # DSPOOFFICIAL100 mandates HTTPS for the callback ("必須在 30 秒內以
+        # HTTPS 回應") — and with no HMAC signing, a plaintext callback URL
+        # would be indefensible anyway.
+        raise DigiwinDsp::ValidationError, "address must be an https:// URL (got #{address.inspect})" unless address.start_with?("https://")
+        return unless address.length > ADDRESS_MAX_LENGTH
+
+        raise DigiwinDsp::ValidationError,
+              "address must be <= #{ADDRESS_MAX_LENGTH} chars (got #{address.length})"
+      end
+
+      def build_body(action:, address:, platform_id:, prod:)
+        resolved = resolve_platform_id(platform_id)
+        request = { "prod" => prod, "platform_id" => resolved, "action" => action, "address" => address }
+        { "digi_body" => { "std_data" => { "parameter" => { "request" => request } } } }
+      end
+
+      def resolve_platform_id(explicit)
+        id = explicit || DigiwinDsp.configuration.platform_id
+        return id unless id.nil? || id.to_s.empty?
+
+        raise DigiwinDsp::ConfigurationError,
+              "platform_id is required (set via configure or pass explicitly)"
+      end
+    end
+  end
+end

data/lib/digiwin_dsp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DigiwinDsp
-  VERSION = "0.2.4"
+  VERSION = "0.3.1"
 end

data/lib/digiwin_dsp/webhooks/event.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DigiwinDsp
+  module Webhooks
+    # Base value-object for an inbound DSP webhook event. Subclasses add
+    # action-specific accessors over the `request` payload but share the
+    # JSON-parse + envelope-extract logic that lives here.
+    class Event
+      attr_reader :digi_header, :request, :raw
+
+      def self.parse(raw_body)
+        hash = parse_json(raw_body)
+        request = extract_request(hash)
+        new(digi_header: hash["digi_header"] || {}, request: request, raw: hash)
+      end
+
+      def self.parse_json(raw_body)
+        # max_nesting mirrors the Client's parser DoS guard.
+        JSON.parse(raw_body, max_nesting: 50)
+      rescue JSON::ParserError => e
+        raise ParseError, "invalid JSON: #{e.message}"
+      end
+
+      def self.extract_request(hash)
+        raise ParseError, "envelope must be a JSON object" unless hash.is_a?(Hash)
+
+        hash.dig("digi_body", "std_data", "parameter", "request") ||
+          raise(ParseError, "envelope missing digi_body.std_data.parameter.request")
+      end
+
+      private_class_method :parse_json, :extract_request
+
+      def initialize(digi_header:, request:, raw:)
+        @digi_header = digi_header
+        @request = request
+        @raw = raw
+      end
+    end
+  end
+end

data/lib/digiwin_dsp/webhooks/inventory_update.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Webhooks
+    # Fired by DSP when an ERP-side inventory change happens.
+    # See docs/dsp-specs/DSPOOFFICIAL100.yaml under
+    # "庫存數量更新 product/inventory_update".
+    class InventoryUpdate < Event
+      def prod         = request["prod"]
+      def platform_id  = request["platform_id"]
+      def sale_page_id = request["sale_page_id"]
+      def spec_list    = request["spec_list"] || []
+    end
+  end
+end

data/lib/digiwin_dsp/webhooks/invoice_update.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Webhooks
+    # Fired by DSP when one or more ERP-issued invoices land. Unlike the
+    # other two events, the request payload is an Array (DSP batches
+    # invoices). See docs/dsp-specs/DSPOOFFICIAL100.yaml under
+    # "發票資料更新 invoice/update".
+    class InvoiceUpdate < Event
+      def self.parse(raw_body)
+        event = super
+        raise ParseError, "invoice/update payload must be an array of invoice records" unless event.request.is_a?(Array)
+
+        event
+      end
+
+      def invoices = request
+    end
+  end
+end

data/lib/digiwin_dsp/webhooks/logistics_update.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  module Webhooks
+    # Fired by DSP when a shipment changes state (handed off to carrier,
+    # delivered, etc.). See docs/dsp-specs/DSPOOFFICIAL100.yaml under
+    # "倉儲貨態更新 wms/logistics/package/update".
+    class LogisticsUpdate < Event
+      def form_no          = request["form_no"]
+      def func_name        = request["func_name"]
+      def status_date      = request["status_date"]
+      def status_time      = request["status_time"]
+      def tracking_number  = request["tracking_number"]
+      def distributor_code = request["distributor_code"]
+      def message          = request["message"]
+    end
+  end
+end

data/lib/digiwin_dsp/webhooks.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DigiwinDsp
+  # Inbound webhook payload parsers for events DSP pushes to your Rails app
+  # after you register a callback URL via `Resources::WebhookSubscription`.
+  #
+  # ⚠️ DSP does NOT sign these requests — there is no HMAC header. Defend
+  # the callback endpoint with HTTPS-only, an unguessable URL path, and
+  # (if possible) an IP allowlist for DSP's egress range.
+  module Webhooks
+    # Raised when JSON is malformed, the envelope is the wrong shape, or
+    # the action is unknown to the gem. Inherits from ValidationError so
+    # Rails controllers can rescue the existing DigiwinDsp::Error tree.
+    class ParseError < DigiwinDsp::ValidationError; end
+
+    # action string => constant name (lazy resolution via const_get so
+    # this module file doesn't force-load the per-event classes at boot).
+    ACTION_REGISTRY = {
+      "product/inventory_update" => :InventoryUpdate,
+      "wms/logistics/package/update" => :LogisticsUpdate,
+      "invoice/update" => :InvoiceUpdate
+    }.freeze
+
+    def self.parse(raw_body, action:)
+      sym = ACTION_REGISTRY[action] ||
+            raise(ParseError, "unknown action #{action.inspect}; expected one of #{ACTION_REGISTRY.keys.inspect}")
+      const_get(sym).parse(raw_body)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: digiwin_dsp
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.1
 platform: ruby
 authors:
 - Zac
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-22 00:00:00.000000000 Z
+date: 2026-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -73,12 +73,18 @@ files:
 - lib/digiwin_dsp/resources/invoice.rb
 - lib/digiwin_dsp/resources/order.rb
 - lib/digiwin_dsp/resources/return.rb
+- lib/digiwin_dsp/resources/webhook_subscription.rb
 - lib/digiwin_dsp/serializers/base.rb
 - lib/digiwin_dsp/serializers/cancellation_serializer.rb
 - lib/digiwin_dsp/serializers/invoice_serializer.rb
 - lib/digiwin_dsp/serializers/return_serializer.rb
 - lib/digiwin_dsp/serializers/sales_order_serializer.rb
 - lib/digiwin_dsp/version.rb
+- lib/digiwin_dsp/webhooks.rb
+- lib/digiwin_dsp/webhooks/event.rb
+- lib/digiwin_dsp/webhooks/inventory_update.rb
+- lib/digiwin_dsp/webhooks/invoice_update.rb
+- lib/digiwin_dsp/webhooks/logistics_update.rb
 homepage: https://github.com/7a6163/digiwin_dsp
 licenses:
 - MIT