nfe-io 0.3.2 → 1.1.0

data/lib/nfe/resources/transportation_invoices.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/inbound_settings"
+require "nfe/resources/dto/inbound_invoice_metadata"
+
+module Nfe
+  module Resources
+    # Inbound CT-e (Conhecimento de Transporte Eletrônico) resource for the
+    # +:cte+ host family (+https://api.nfse.io+). Manages automatic CT-e fetch
+    # via SEFAZ Distribuição DFe and reads received CT-e documents/events by
+    # 44-digit access key.
+    #
+    # This is an inbound/query resource (settings + access-key lookups), not an
+    # emission resource: there is no discriminated 202 +Pending+/+Issued+
+    # contract here. The host already carries no version segment, so paths embed
+    # +/v2+ literally and {#api_version} is +""+.
+    #
+    # @example Enable auto-fetch and read a received CT-e
+    #   client.transportation_invoices.enable(company_id: "co-1")
+    #   cte = client.transportation_invoices.retrieve(
+    #     company_id: "co-1",
+    #     access_key: "3524...7890"
+    #   )
+    class TransportationInvoices < AbstractResource
+      protected
+
+      def api_family
+        :cte
+      end
+
+      # The +:cte+ host carries no version segment; +/v2+ is embedded per path.
+      def api_version
+        ""
+      end
+
+      public
+
+      # Enable automatic CT-e search for a company via Distribuição DFe.
+      #
+      # @param company_id [String]
+      # @param start_from_nsu [Integer, String, nil] optional starting NSU.
+      # @param start_from_date [String, nil] optional starting date (ISO 8601).
+      # @return [Nfe::InboundSettings]
+      def enable(company_id:, start_from_nsu: nil, start_from_date: nil)
+        id = Nfe::IdValidator.company_id(company_id)
+        body = compact("startFromNsu" => start_from_nsu, "startFromDate" => start_from_date)
+        response = post("/v2/companies/#{id}/inbound/transportationinvoices",
+                        body: json_body(body), headers: json_headers)
+        hydrate(Nfe::InboundSettings, parse_json(response.body))
+      end
+
+      # Disable automatic CT-e search for a company.
+      #
+      # @param company_id [String]
+      # @return [Nfe::InboundSettings]
+      def disable(company_id:)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = delete("/v2/companies/#{id}/inbound/transportationinvoices")
+        hydrate(Nfe::InboundSettings, parse_json(response.body))
+      end
+
+      # Get the current automatic CT-e search settings.
+      #
+      # @param company_id [String]
+      # @return [Nfe::InboundSettings]
+      def get_settings(company_id:)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = get("/v2/companies/#{id}/inbound/transportationinvoices")
+        hydrate(Nfe::InboundSettings, parse_json(response.body))
+      end
+
+      # Retrieve CT-e metadata by its 44-digit access key (normalized).
+      #
+      # @param company_id [String]
+      # @param access_key [String] 44-digit key; separators are stripped.
+      # @return [Nfe::InboundInvoiceMetadata]
+      def retrieve(company_id:, access_key:)
+        id = Nfe::IdValidator.company_id(company_id)
+        key = Nfe::IdValidator.access_key(access_key)
+        response = get("/v2/companies/#{id}/inbound/#{key}")
+        hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
+      end
+
+      # Download the CT-e XML by access key.
+      #
+      # @param company_id [String]
+      # @param access_key [String]
+      # @return [String] raw XML bytes (+ASCII-8BIT+).
+      def download_xml(company_id:, access_key:)
+        id = Nfe::IdValidator.company_id(company_id)
+        key = Nfe::IdValidator.access_key(access_key)
+        download("/v2/companies/#{id}/inbound/#{key}/xml", headers: xml_accept)
+      end
+
+      # Retrieve the metadata of an event related to a received CT-e.
+      #
+      # @param company_id [String]
+      # @param access_key [String]
+      # @param event_key [String]
+      # @return [Nfe::InboundInvoiceMetadata]
+      def get_event(company_id:, access_key:, event_key:)
+        id = Nfe::IdValidator.company_id(company_id)
+        key = Nfe::IdValidator.access_key(access_key)
+        ev = Nfe::IdValidator.event_key(event_key)
+        response = get("/v2/companies/#{id}/inbound/#{key}/events/#{ev}")
+        hydrate(Nfe::InboundInvoiceMetadata, parse_json(response.body))
+      end
+
+      # Download the XML of a CT-e event.
+      #
+      # @param company_id [String]
+      # @param access_key [String]
+      # @param event_key [String]
+      # @return [String] raw XML bytes (+ASCII-8BIT+).
+      def download_event_xml(company_id:, access_key:, event_key:)
+        id = Nfe::IdValidator.company_id(company_id)
+        key = Nfe::IdValidator.access_key(access_key)
+        ev = Nfe::IdValidator.event_key(event_key)
+        download("/v2/companies/#{id}/inbound/#{key}/events/#{ev}/xml", headers: xml_accept)
+      end
+
+      private
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+
+      def json_body(data)
+        JSON.generate(data)
+      end
+
+      def xml_accept
+        { "Accept" => "application/xml" }
+      end
+
+      # Drop +nil+ values so optional fields are omitted from the body.
+      def compact(hash)
+        hash.compact
+      end
+    end
+  end
+end

data/lib/nfe/resources/webhooks.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "json"
+require "nfe/resources/abstract_resource"
+require "nfe/resources/dto/account_webhook"
+require "nfe/resources/dto/webhook"
+require "nfe/webhook"
+
+module Nfe
+  module Resources
+    # Webhooks resource on the +:main+ host family.
+    #
+    # Webhooks are managed at the **account** level over +/v2/webhooks+ — use
+    # the +*_account_webhook*+ methods. The live API wraps create/update
+    # requests and single-object responses in a +webHook+ envelope; the SDK
+    # envelopes/unwraps transparently. Contract source of truth:
+    # +openapi/nf-servico-v1.yaml+ plus live probes (2026-07-02/03).
+    #
+    # The company-scoped methods (+list+/+create+/+retrieve+/+update+/
+    # +delete+/+test+ under +/v1/companies/{id}/webhooks+) are deprecated: the
+    # route returns 404 on the current API (confirmed on three accounts,
+    # 2026-07-02/03). They remain, unchanged, until the next major.
+    #
+    # Also exposes a thin {#verify_signature} delegation to {Nfe::Webhook}
+    # (the canonical signature-verification API is the module).
+    class Webhooks < AbstractResource
+      # Preserve the inherited HTTP DELETE helper under a private name before
+      # the public company-scoped +delete+ shadows it — the account-scoped
+      # deletes still need the raw verb.
+      alias http_delete delete
+      private :http_delete
+
+      # Legacy static list of event types.
+      #
+      # @deprecated These literals do not exist on the live API — the real
+      #   event types follow +service_invoice.*+/+product_invoice.*+/
+      #   +consumer_invoice.*+ (46 ids live). Use {#fetch_event_types}.
+      AVAILABLE_EVENTS = %w[
+        invoice.issued
+        invoice.cancelled
+        invoice.failed
+        invoice.processing
+        company.created
+        company.updated
+        company.deleted
+      ].freeze
+
+      protected
+
+      def api_family
+        :main
+      end
+
+      # Account-scoped endpoints live under +/v2+ on the same +:main+ host,
+      # while the (deprecated) company-scoped ones keep the resource default
+      # +/v1+. A path that already carries an explicit version segment passes
+      # through unprefixed.
+      def full_path(path)
+        path.start_with?("/v2/") ? path : super
+      end
+
+      public
+
+      # List the account's webhooks (+GET /v2/webhooks+).
+      #
+      # The API wraps the collection as +{"webHooks": [...]}+; the SDK unwraps
+      # it into an {Nfe::ListResponse} of {Nfe::AccountWebhook}. +secret+ is
+      # omitted on reads.
+      #
+      # @return [Nfe::ListResponse]
+      def list_account_webhooks
+        response = get("/v2/webhooks")
+        hydrate_list(Nfe::AccountWebhook, parse_json(response.body), wrapper_key: "webHooks")
+      end
+
+      # Create an account webhook (+POST /v2/webhooks+).
+      #
+      # The request is wrapped in the mandatory +webHook+ envelope (the API
+      # rejects a bare body with +400 "missing required properties: 'webHook'"+)
+      # and the +201 {"webHook": {...}}+ response is unwrapped.
+      #
+      # NFE.io **pings the +uri+ at creation time and requires a 2xx
+      # response** — the endpoint must already be live, or the create fails.
+      # +secret+ must be 32–64 characters; it is echoed back on create and
+      # omitted on subsequent reads.
+      #
+      # @param data [Hash] webhook attributes in wire (camelCase) keys, e.g.
+      #   +{ uri: "https://...", contentType: "json", secret: "<32-64 chars>",
+      #   filters: ["service_invoice.issued_successfully"], status: "Active" }+.
+      #   Discover valid +filters+ with {#fetch_event_types}.
+      # @return [Nfe::AccountWebhook]
+      def create_account_webhook(data)
+        response = post("/v2/webhooks",
+                        body: json_body({ webHook: data }), headers: json_headers)
+        hydrate_account_webhook(response)
+      end
+
+      # Retrieve an account webhook by id (+GET /v2/webhooks/{id}+).
+      #
+      # Unwraps the +{"webHook": {...}}+ envelope, falling back to the raw
+      # body when the envelope is absent. +secret+ is omitted on reads.
+      #
+      # @param webhook_id [String]
+      # @return [Nfe::AccountWebhook]
+      def retrieve_account_webhook(webhook_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = get("/v2/webhooks/#{wid}")
+        hydrate_account_webhook(response)
+      end
+
+      # Update an account webhook (+PUT /v2/webhooks/{id}+), request wrapped
+      # in the +webHook+ envelope.
+      #
+      # @note **+PUT+ is a full replacement** (live-confirmed 2026-07-03):
+      #   omitted fields reset to their defaults — an update without +status+
+      #   **deactivates the webhook**. Always send the complete object,
+      #   starting from a retrieve:
+      #
+      #     current = client.webhooks.retrieve_account_webhook(id)
+      #     client.webhooks.update_account_webhook(id, {
+      #       uri: current.uri,
+      #       contentType: current.content_type,
+      #       status: current.status,            # keep it "Active"!
+      #       filters: ["service_invoice.issued_successfully"]
+      #     })
+      #
+      # @param webhook_id [String]
+      # @param data [Hash] the complete webhook attributes (wire camelCase keys).
+      # @return [Nfe::AccountWebhook]
+      def update_account_webhook(webhook_id, data)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = put("/v2/webhooks/#{wid}",
+                       body: json_body({ webHook: data }), headers: json_headers)
+        hydrate_account_webhook(response)
+      end
+
+      # Delete a single account webhook by id (+DELETE /v2/webhooks/{id}+).
+      #
+      # @param webhook_id [String]
+      # @return [nil]
+      def delete_account_webhook(webhook_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        http_delete("/v2/webhooks/#{wid}")
+        nil
+      end
+
+      # ⚠️ DESTRUCTIVE: delete **ALL** of the account's webhooks
+      # (+DELETE /v2/webhooks+). Named distinctly from
+      # {#delete_account_webhook} so it can never be reached by a mistyped
+      # single delete.
+      #
+      # @return [nil]
+      def delete_all_account_webhooks
+        http_delete("/v2/webhooks")
+        nil
+      end
+
+      # Trigger a test ping for an account webhook
+      # (+PUT /v2/webhooks/{id}/pings+, responds 204).
+      #
+      # @param webhook_id [String]
+      # @return [nil]
+      def ping_account_webhook(webhook_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        put("/v2/webhooks/#{wid}/pings", body: json_body({}), headers: json_headers)
+        nil
+      end
+
+      # Fetch the live list of webhook event types
+      # (+GET /v2/webhooks/eventTypes+).
+      #
+      # The API wraps the result as +{"eventTypes": [{ "id": ... }, ...]}+;
+      # this extracts the ids (e.g. +"service_invoice.issued_successfully"+,
+      # +"product_invoice.issued"+ — 46 ids live). Use these as +filters+ when
+      # creating or updating a webhook.
+      #
+      # @return [Array<String>]
+      def fetch_event_types
+        response = get("/v2/webhooks/eventTypes")
+        payload = parse_json(response.body)
+        items = [] #: Array[untyped]
+        items = payload["eventTypes"] || items if payload.is_a?(Hash)
+        items.map { |item| item["id"] }.compact
+      end
+
+      # List a company's webhook subscriptions.
+      #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#list_account_webhooks}.
+      #
+      # @param company_id [String]
+      # @return [Nfe::ListResponse]
+      def list(company_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = get("/companies/#{id}/webhooks")
+        payload = parse_json(response.body)
+        items = webhook_items(payload).map { |item| hydrate(Nfe::WebhookSubscription, item) }
+        Nfe::ListResponse.new(data: items)
+      end
+
+      # Create a webhook subscription. Accepts +url+, +events+, +secret+, +active+.
+      #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#create_account_webhook}.
+      #
+      # @param company_id [String]
+      # @param data [Hash]
+      # @return [Nfe::WebhookSubscription, nil]
+      def create(company_id, data)
+        id = Nfe::IdValidator.company_id(company_id)
+        response = post("/companies/#{id}/webhooks",
+                        body: json_body(data), headers: json_headers)
+        hydrate(Nfe::WebhookSubscription, parse_json(response.body))
+      end
+
+      # Retrieve a webhook by id.
+      #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#retrieve_account_webhook}.
+      #
+      # @param company_id [String]
+      # @param webhook_id [String]
+      # @return [Nfe::WebhookSubscription, nil]
+      def retrieve(company_id, webhook_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = get("/companies/#{id}/webhooks/#{wid}")
+        hydrate(Nfe::WebhookSubscription, parse_json(response.body))
+      end
+
+      # Update a webhook.
+      #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#update_account_webhook}.
+      #
+      # @param company_id [String]
+      # @param webhook_id [String]
+      # @param data [Hash]
+      # @return [Nfe::WebhookSubscription, nil]
+      def update(company_id, webhook_id, data)
+        id = Nfe::IdValidator.company_id(company_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = put("/companies/#{id}/webhooks/#{wid}",
+                       body: json_body(data), headers: json_headers)
+        hydrate(Nfe::WebhookSubscription, parse_json(response.body))
+      end
+
+      # Delete a webhook.
+      #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#delete_account_webhook}.
+      #
+      # @param company_id [String]
+      # @param webhook_id [String]
+      # @return [nil]
+      def delete(company_id, webhook_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        super("/companies/#{id}/webhooks/#{wid}")
+        nil
+      end
+
+      # Trigger a synthetic delivery to verify a webhook is reachable.
+      #
+      # @deprecated The +/v1/companies/{id}/webhooks+ route returns 404 on the
+      #   current API (confirmed on three accounts, 2026-07-02/03). Use
+      #   {#ping_account_webhook}.
+      #
+      # @param company_id [String]
+      # @param webhook_id [String]
+      # @return [Hash] +{ success: bool, message: String? }+.
+      def test(company_id, webhook_id)
+        id = Nfe::IdValidator.company_id(company_id)
+        wid = Nfe::IdValidator.presence!(webhook_id, "webhook_id")
+        response = post("/companies/#{id}/webhooks/#{wid}/test",
+                        body: json_body({}), headers: json_headers)
+        payload = parse_json(response.body) || {}
+        { success: payload["success"] || false, message: payload["message"] }
+      end
+
+      # The legacy static list of webhook event types.
+      #
+      # @deprecated These literals do not exist on the live API. Use
+      #   {#fetch_event_types} for the real, live list.
+      #
+      # @return [Array<String>]
+      def get_available_events
+        AVAILABLE_EVENTS.dup
+      end
+
+      # Verify a webhook signature. Thin delegation to {Nfe::Webhook} for Node
+      # parity; the canonical API is the module. Never raises.
+      #
+      # @return [Boolean]
+      def verify_signature(payload:, signature:, secret:)
+        Nfe::Webhook.verify_signature(payload: payload, signature: signature, secret: secret)
+      end
+
+      private
+
+      # Unwrap a single-object +{"webHook": {...}}+ envelope (raw-body
+      # fallback) and hydrate an {Nfe::AccountWebhook}.
+      def hydrate_account_webhook(response)
+        hydrate(Nfe::AccountWebhook, unwrap(parse_json(response.body), "webHook"))
+      end
+
+      def json_headers
+        { "Content-Type" => "application/json" }
+      end
+
+      def json_body(data)
+        JSON.generate(data)
+      end
+
+      # Tolerate either a bare array, a +data+-wrapped list, or a +webhooks+
+      # envelope for the (deprecated) company-scoped list response.
+      def webhook_items(payload)
+        return payload if payload.is_a?(Array)
+        return [] unless payload.is_a?(Hash)
+
+        payload["data"] || payload["webhooks"] || payload[:data] || payload[:webhooks] || []
+      end
+    end
+  end
+end

data/lib/nfe/results.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Result of an asynchronous (HTTP 202) invoice operation: the API accepted
+  # the request and is processing it. The document is not yet materialized.
+  #
+  # +invoice_id+ is parsed from the +Location+ header's final path segment;
+  # +location+ is the raw header value. Discriminate against {Nfe::Issued} with
+  # +is_a?+/+case+ and poll {Nfe::FlowStatus.terminal?} until settled.
+  class Pending < Data.define(:invoice_id, :location)
+  end
+
+  # Result of a synchronous (HTTP 201/200) invoice operation: the document was
+  # materialized immediately. +resource+ is the hydrated DTO value object.
+  class Issued < Data.define(:resource)
+  end
+end

data/lib/nfe/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Nfe
-  VERSION = "0.3.2"
+  VERSION = "1.1.0"
 end

data/lib/nfe/webhook.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module Nfe
+  # Stateless helpers for verifying NFE.io webhook deliveries. This is the
+  # canonical signature-verification API: it needs no {Nfe::Client}, reads no
+  # {Nfe::Configuration}, and performs no network access — the caller supplies
+  # the raw payload bytes, the +X-Hub-Signature+ header value, and the secret.
+  #
+  # == IMPORTANT: pass the RAW request body bytes
+  # NFE.io signs the exact bytes it delivered. Read the raw body BEFORE parsing
+  # JSON (e.g. +request.body.read+ in Rack/Rails) and pass those bytes. Do NOT
+  # re-serialize a parsed object (+payload.to_json+) — key order and whitespace
+  # will differ from the signed bytes and verification will fail unpredictably.
+  #
+  #   raw = request.body.read
+  #   sig = request.get_header("HTTP_X_HUB_SIGNATURE")
+  #   if Nfe::Webhook.verify_signature(payload: raw, signature: sig, secret: ENV["NFE_WEBHOOK_SECRET"])
+  #     event = Nfe::Webhook.construct_event(payload: raw, signature: sig, secret: ENV["NFE_WEBHOOK_SECRET"])
+  #     # event.id => dedupe on this; NFE.io sends no timestamp/nonce, so a valid
+  #     # signature proves authenticity but NOT freshness. Handlers MUST be
+  #     # idempotent and dedupe on the event/invoice id.
+  #   end
+  #
+  # Only the +X-Hub-Signature+ + HMAC-SHA1 scheme is supported. The legacy
+  # +X-NFe-Signature+ / HMAC-SHA256 scheme is intentionally NOT implemented; a
+  # +sha256=+ header is rejected.
+  module Webhook
+    # Wire prefix on the +X-Hub-Signature+ header value.
+    SIGNATURE_PREFIX = "sha1="
+    private_constant :SIGNATURE_PREFIX
+
+    # HMAC-SHA1 hex digests are always 40 lowercase hex characters.
+    HEX_RE = /\A[a-f0-9]{40}\z/
+    private_constant :HEX_RE
+
+    module_function
+
+    # Verify an +X-Hub-Signature+ value against the payload and secret using
+    # constant-time comparison. Returns +true+ only on an exact HMAC-SHA1 match.
+    #
+    # Never raises: any missing, malformed, wrong-algorithm, wrong-length, or
+    # non-hex input yields +false+.
+    #
+    # @param payload [String] the raw, byte-exact request body.
+    # @param signature [String, Array<String>, nil] the +X-Hub-Signature+ value;
+    #   a single-element Array (repeated-header shape) uses its first element.
+    # @param secret [String, nil] the webhook secret.
+    # @return [Boolean]
+    def verify_signature(payload:, signature:, secret:)
+      return false if secret.nil? || secret.to_s.empty?
+
+      signature = signature.first if signature.is_a?(Array)
+      return false if signature.nil?
+
+      signature = signature.to_s
+      return false if signature.empty?
+      return false unless signature[0, SIGNATURE_PREFIX.length].to_s.downcase == SIGNATURE_PREFIX
+
+      received = signature[SIGNATURE_PREFIX.length..].to_s.downcase
+      return false unless HEX_RE.match?(received)
+
+      expected = OpenSSL::HMAC.hexdigest("SHA1", secret, payload.to_s)
+      OpenSSL.secure_compare(received, expected)
+    rescue StandardError
+      false
+    end
+
+    # Verify, then parse and unwrap a delivery into a {Nfe::WebhookEvent}.
+    #
+    # @param payload [String] the raw, byte-exact request body.
+    # @param signature [String, Array<String>, nil] the +X-Hub-Signature+ value.
+    # @param secret [String, nil] the webhook secret.
+    # @return [Nfe::WebhookEvent]
+    # @raise [Nfe::SignatureVerificationError] when the signature does not match
+    #   or the payload is not valid JSON.
+    def construct_event(payload:, signature:, secret:)
+      unless verify_signature(payload: payload, signature: signature, secret: secret)
+        raise Nfe::SignatureVerificationError, "Assinatura de webhook inválida."
+      end
+
+      decoded = parse_payload(payload)
+      build_event(decoded)
+    end
+
+    # @api private
+    def parse_payload(payload)
+      decoded = JSON.parse(payload.to_s)
+      unless decoded.is_a?(Hash)
+        raise Nfe::SignatureVerificationError, "Payload de webhook não decodificou para um objeto."
+      end
+
+      decoded
+    rescue JSON::ParserError
+      raise Nfe::SignatureVerificationError, "Payload de webhook não é JSON válido."
+    end
+
+    # Unwrap the +action+/+payload+ or +event+/+data+ envelope into a
+    # {Nfe::WebhookEvent}; falls back to a flat +type+/+event_type+/+action+
+    # shape carrying the whole body as +data+.
+    #
+    # @api private
+    def build_event(decoded)
+      type = first_string(decoded, "action", "event", "type", "event_type")
+      data = envelope_data(decoded)
+
+      Nfe::WebhookEvent.new(
+        type: type,
+        data: data,
+        id: nullable_string(decoded["id"] || data["id"]),
+        created_at: nullable_string(decoded["createdAt"] || data["createdAt"])
+      )
+    end
+
+    # @api private
+    def envelope_data(decoded)
+      candidate = decoded["payload"] || decoded["data"]
+      candidate.is_a?(Hash) ? candidate : decoded
+    end
+
+    # @api private
+    def first_string(hash, *keys)
+      keys.each do |key|
+        value = hash[key]
+        return value if value.is_a?(String) && !value.empty?
+      end
+      nil
+    end
+
+    # @api private
+    def nullable_string(value)
+      value.is_a?(String) ? value : nil
+    end
+  end
+end

data/lib/nfe/webhook_event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Nfe
+  # Immutable value object for a verified webhook delivery, produced by
+  # {Nfe::Webhook.construct_event} after the HMAC-SHA1 signature checks out.
+  #
+  # - +type+ is the event type (e.g. +"service_invoice.issued_successfully"+), unwrapped from the
+  #   delivery envelope's +action+ or +event+ key.
+  # - +data+ is the payload +Hash+ (the envelope's +payload+ or +data+ key).
+  # - +id+ is a stable event/invoice id for deduplication, or +nil+ when the
+  #   envelope carries none. NFE.io sends no timestamp/nonce, so a valid
+  #   signature proves authenticity but NOT freshness — handlers MUST be
+  #   idempotent and dedupe on this id.
+  # - +created_at+ is the delivery timestamp string, or +nil+.
+  class WebhookEvent < Data.define(:type, :data, :id, :created_at)
+    # Allow +id+ and +created_at+ to default to +nil+ so callers (and
+    # +construct_event+) can omit them.
+    def initialize(type:, data:, id: nil, created_at: nil)
+      super
+    end
+  end
+end