spree_uber_direct 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8e0793a132d883c5102169e0cdde12d41142ff2970a83a562e3a859c9cee04dc
+  data.tar.gz: 15ef632876eee5186617f043d917f4ce52c15001c72767a16e3e63535a24c66e
+SHA512:
+  metadata.gz: 3a52b2f8721b956c79abab2b34d3e4941a44fa7cc1aa73e1712df17dfcee2b6f3af2ae3f2bb99b1337346793ba0cf4ed702cc560b7e4b205a901fd8dd1d540f2
+  data.tar.gz: c251297570f0d3b593e254135f01606563b6718c9712c30a3091c4ccb0434769f6430bb5379b07b7e5d8fae6415c530bb15b2253f8a88a6f52fba06c397f1dd3

data/.env

@@ -0,0 +1,7 @@
+# Loaded via `dotenv/load` in spec/spec_helper.rb, for the dummy test app
+# only — not read by anything that ships. Test-only Active Record Encryption
+# keys (SpreeUberDirect::Credential) so specs can save/load encrypted
+# columns; generated with SecureRandom, no real secret behind them.
+ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=n9E5F4KLb9C8VyQ2ZmXtRj7WuHsPaTgD
+ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=Qw3RtYpAsDfGhJkLzXcVbNm5UiOp9Egh
+ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=Zx8CvBnM4QwErTyU6IoPaSdFgHjKlBcv

data/.gitignore

@@ -0,0 +1,27 @@
+\#*
+*~
+.#*
+.DS_Store
+.idea
+.localeapp/locales
+.project
+.vscode
+coverage
+default
+Gemfile.lock
+tmp
+nbproject
+pkg
+*.sw?
+spec/dummy
+.rvmrc
+.sass-cache
+public/spree
+.ruby-version
+.ruby-gemset
+*.gem
+*/*.gem
+
+# Real Uber Direct Sandbox credentials for manual verification — never committed,
+# unlike the test-only encryption keys in .env.
+.env.sandbox

data/.rspec

@@ -0,0 +1,3 @@
+--color
+-r spec_helper
+-f documentation

data/CHANGELOG.md

@@ -0,0 +1,170 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.1.4
+
+Reverses part of 0.1.1's own safety decision, deliberately: Robo Courier is now gated on the credential's
+`uber_environment: sandbox` flag alone again, not also on `!Rails.env.production?`. Explicit, informed call
+by the project owner after 0.1.1's own change shipped — this storefront is a demo running end to end on
+sandbox credentials (Square, DoorDash, Uber alike) regardless of Rails environment, and showing a real
+visitor the full Uber Direct delivery lifecycle live is the intended demo experience, not an accident to
+guard against. Flagged in code review as a real, accepted tradeoff rather than silently dropped: every
+production dispatch now also drives ~6 Robo Courier webhook calls against Uber's real Sandbox rate limit
+(200 req/10min per application_id) — fine at this project's traffic scale, worth revisiting if that changes.
+
+## 0.1.3
+
+Closes the `event.refund_request` gap 0.1.2 flagged as a follow-up: those payloads were being acked and
+dropped alongside genuinely-disposable `event.courier_update` pings, but a refund notification carries real,
+unrecoverable data (`data.id`, `currency_code`, `total_partner_refund`, `total_uber_refund`, `refund_fees`,
+`refund_order_items` — confirmed against
+[Uber's own webhook docs](https://developer.uber.com/docs/deliveries/daas/api/webhook-event-refundrequest)).
+
+Adds `SpreeUberDirect::RefundEvent` — same idempotency-key shape as `WebhookEvent` (`delivery_id` + a digest
+of the raw body, deduping Uber's at-least-once webhook redelivery) but deliberately without any of
+`WebhookEvent`'s processing-state tracking (`processing_status`/`processed_at`/`error_message`), since
+there's no consumer for this data yet. `WebhooksController#create` now branches on
+`payload['kind'] == 'event.refund_request'` ahead of the generic blank-status drop and persists the full
+payload there instead. No processing/business logic added — purely a durable record for whenever refund
+reconciliation admin UI or accounting sync becomes a real need.
+
+**Code review caught a real bug before merge**: the first pass used a bare `RefundEvent.create!`, which
+raised `ActiveRecord::RecordInvalid` (reproduced directly) for any payload missing a top-level `delivery_id`
+— crashing instead of acking, and risking Uber retrying (and eventually disabling) the webhook subscription
+on a payload that would keep failing identically. Fixed by routing through the same
+find-or-create-with-digest + rescue shape `WebhookEvent`'s own path already uses.
+
+## 0.1.2
+
+Fixes a real bug found live while verifying 0.1.1's Robo Courier run through a real ngrok-tunneled
+dispatch: Uber's dashboard lets one webhook subscribe to three event kinds on the same endpoint —
+`event.delivery_status` (the only one with a top-level `status` field), `event.courier_update` (a courier
+GPS ping fired every 20s once a courier is assigned), and `event.refund_request` (fired when a refund is
+requested, confirmed against Uber's own webhook docs). Neither of the latter two carries a `status` field,
+but `WebhooksController` always built its `WebhookEvent` with `status: payload['status']`, and
+`WebhookEvent` requires status presence — every courier-location ping was hitting an unhandled
+`ActiveRecord::RecordNotFound` and surfacing as a bare `404` to Uber's webhook delivery system. The
+controller now acks and drops any payload with a blank status before it reaches `WebhookEvent`, with a
+debug-level log line so the drop stays traceable. `event.refund_request` payloads are currently discarded
+the same way — a real gap (refund data isn't persisted anywhere yet) flagged as a follow-up, not built
+here.
+
+**Verified live**: re-dispatched a real order through the real `DeliveryDispatcher` with Robo Courier
+enabled, watched it progress through the full real lifecycle (`pending` → `pickup` → `dropoff` →
+`delivered`, 8 real webhooks) through the ngrok tunnel with zero 404s afterward.
+
+## 0.1.1
+
+Sandbox delivery dispatch now requests Uber's **Robo Courier** test-automation feature
+(`test_specifications.robo_courier_specification.mode: "auto"` on `POST /deliveries`) — Uber Direct has
+no dashboard "simulate delivery" UI the way DoorDash's own Delivery Simulator works; this is its actual
+equivalent. Without it, a sandbox delivery only ever emitted its initial `pending` webhook and then went
+silent forever (no real driver app was ever going to advance it), which is exactly what this closes.
+
+**Verified live**: dispatched a real order through the real `DeliveryDispatcher` (not a console script)
+against a real Uber Direct Sandbox account, tunneled through ngrok to a local dev server with a real
+registered webhook + signing secret — a real `pending` webhook landed, signature-verified, immediately on
+dispatch, closing out the one remaining gap between this extension's Sandbox setup and `spree_doordash`'s.
+
+Gated on **two independent conditions**, not just the credential's `uber_environment` field — code review
+caught that this project's own live production deploy runs against a genuinely `uber_environment: sandbox`
+credential (Uber has not yet granted production API access), so trusting that field alone would have
+silently faked delivery-status progression for real customer orders if this ever shipped to production.
+Robo Courier now also requires `!Rails.env.production?`.
+
+## 0.1.0 (released)
+
+A second, independent delivery provider alongside `spree_doordash` — same one-extension-per-integration
+pattern already established by `spree_square`/`spree_doordash`/`spree_menu_chat`/`spree_loyalty`, offered
+as a third shipping-method choice (Pickup, DoorDash Delivery, Uber Direct Delivery) rather than a
+replacement for either.
+
+**M1 — Foundation.** Gemspec, engine, `Credential` (OAuth2 `client_credentials` — client_id/client_secret/
+customer_id, cached access token with expiry-aware refresh keyed off the credential's own `updated_at` so
+a rotated secret takes effect immediately, webhook signing key), admin credential form, `Client` service
+(token fetch/cache, `create_quote`/`create_delivery`/`get_delivery`/`cancel_delivery`). **Verified against
+a real Uber Direct Sandbox account**: a real OAuth token was fetched from `auth.uber.com/oauth/v2/token`
+and accepted by a real `POST /v1/customers/{customer_id}/delivery_quotes` call (real `400 invalid_params`
+for an intentionally-incomplete payload, not `401`/`403`).
+
+**M2 — Quoting.** `QuoteMapping` + `Quote` service. Simpler than DoorDash's own quote tracking in two ways
+confirmed against Uber's real `openapi.yaml` (`github.com/uber/uber-direct-sdk`): the quote id is
+server-generated and returned fresh on every call (no client-side id-collision risk DoorDash's own
+`external_delivery_id` needed a random suffix to dodge), and Uber returns its own real `expires` timestamp
+instead of a hardcoded documented window. Addresses are JSON-encoded strings
+(`{"street_address":[...],"city":...}`), not DoorDash's flat comma-joined string — confirmed directly
+against the schema, not guessed. **Verified live**: a New York dropoff correctly got a real
+`400 address_undeliverable` (412mi from the Fairview Park, OH pickup, outside Uber's 10mi radius — a true
+rejection, not a bug), and a real nearby Ohio address got a real accepted quote ($7.99, 15-minute expiry).
+
+**M3 — Storefront quoting.** `Spree::Calculator::Shipping::UberDirectQuote` reuses the same
+zero-registration `Spree::ShippingCalculator` subclass mechanism `DoordashQuote` already proved out, and
+the same `Thread.current` object-identity bridge for pushing an unavailable-quote warning onto the real
+order (`package.order` is a distinct in-memory object from what `create_proposed_shipments` holds — see
+`spree_doordash`'s own 0.1.3 for the full root-cause story this reuses verbatim).
+`SpreeUberDirect::OrderDecorator` does the merge-back half — deliberately namespaced (not the bare
+`Spree::OrderDecorator` name `spree_doordash` already claims) so both gems' prepended modules chain
+correctly via `super` instead of one silently overwriting the other. No storefront (Next.js) code changes
+needed. **Verified live**: a real checkout showed all three shipping methods together — Pickup $0.00, Uber
+Direct Delivery $7.99 (+ tax), DoorDash Delivery $9.75 (+ tax) — confirming both delivery providers coexist
+without either's decorator clobbering the other.
+
+**M4 — Dispatch + webhooks.** `DeliveryMapping` (Uber mints a genuinely separate `del_`-prefixed delivery
+id on `POST /deliveries`, unlike DoorDash which reuses the accepted quote's own id for the delivery's whole
+lifecycle), `WebhookEvent` (idempotency key is `delivery_id` + `status` + a payload digest — Uber's
+webhooks carry one event kind, `event.delivery_status`, with no distinct event id, the same gap DoorDash's
+own webhooks have; the DB column holding *our own* pending/processed/failed tracking is named
+`processing_status`, not `status`, specifically to avoid colliding with Uber's own delivery status value
+which is genuinely called `status` in their payload). `WebhookVerifier` is architecturally different from
+DoorDash's Basic-Auth string echo: real HMAC-SHA256 over the raw body via `x-uber-signature`, keyed by a
+dedicated webhook signing secret (confirmed against developer.uber.com's webhook guide — a separate value
+from the OAuth `client_secret`). `DeliveryDispatcher`/`DeliveryStatusMapper`/`WebhooksController`/
+`DeliveryWebhookJob`/`DeliveryDispatchJob`/`OrderCompletedSubscriber`/`Alerting` all mirror their DoorDash
+counterparts' exact shapes, adapted to Uber's real status vocabulary (`pending`/`pickup`/`pickup_complete`/
+`dropoff`/`delivered`/`canceled`/`returned`/`shopping_completed`). Critically included
+`config/initializers/spree.rb` registering the subscriber with `Spree.subscribers` — without it the
+subscriber is real and loadable (specs calling it directly always pass) but never actually wired to a real
+`order.completed` event, the exact silent gap `spree_doordash`'s own CHANGELOG documents finding live.
+
+A real bug found live during this milestone's own verification: `DeliveryDispatcher` initially sent only
+`{quote_id: ...}` to `POST /deliveries` — a real Sandbox `400` (`invalid_params`: `pickup_name`/
+`dropoff_name`/`manifest` required) proved Uber's `DeliveryReq` needs a full payload even with a `quote_id`
+attached, unlike DoorDash's `accept_quote` (which only needs the id). Extracted address/phone formatting
+into a shared `AddressPayload` module (used by both `Quote` and `DeliveryDispatcher`) rather than
+duplicating it.
+
+**M5 — Admin UI + real Sandbox end-to-end verification.** Read-only admin pages for `DeliveryMapping`/
+`WebhookEvent` (four-file pattern, including the `new_resource: false` fix both `spree_square` and
+`spree_doordash` had to learn the hard way on their first real Postgres run — repeated here from the start
+via `Rails.application.config.after_initialize`, needed because a running dev process doesn't hot-reload a
+newly-added initializer file the way autoloaded `app/` code does, confirmed live via a real
+`NoMethodError: Table 'uber_direct_delivery_mappings' has not been registered` until the process was
+restarted). Nav positions 77–78 (credential itself at 76 from M1).
+
+**Verified against real Uber Direct Sandbox infrastructure end to end, not just specs** — the same
+standard every prior integration in this project was held to:
+- A real order dispatched a real delivery using Uber's **Robo Courier** test feature
+  (`test_specifications.robo_courier_specification.mode: "auto"` — the Sandbox equivalent of DoorDash's own
+  Delivery Simulator, confirmed via live research, not assumed).
+- Polled the real delivery and watched it progress through Uber's actual lifecycle end to end: `pending` →
+  `pickup` → `dropoff` → `delivered`, with a real assigned test courier ("Alex H.") and `complete: true`.
+- Fed that real `delivered` payload through `DeliveryStatusMapper` and confirmed it correctly recorded
+  `last_status`/`courier_name`/`courier_phone` from Uber's real response shape.
+- Both new admin pages (`/admin/uber_direct_delivery_mappings`, `/admin/uber_direct_webhook_events`) and the
+  credential page confirmed loading against real Postgres data — all three real dispatch attempts from this
+  session (including the earlier payload-bug 400) visible in the table.
+- **Not live-tested this milestone**: inbound webhook *receiving* (a live POST from Uber hitting a real
+  registered endpoint) — no public tunnel/registered webhook URL was set up in this session. The
+  controller's signature verification, idempotency, and job dispatch are covered by real HMAC-signed
+  request specs instead; genuinely receiving a live webhook remains open for whenever a tunnel is set up.
+- `shipment.ship!` itself was not re-exercised live in this specific run (the verification order was built
+  directly via console rather than walked through Spree's full checkout state machine, so the shipment
+  never reached `ready`) — covered instead by a passing unit spec using a `ready`-state shipment.
+
+101 examples, 0 failures across the full suite. Not yet tagged, pushed to a remote, or released to
+RubyGems — kept local-only per explicit instruction.
+
+**M6 (spec coverage/docs) and M7 (go-live) not started** — M7 is gated entirely on Uber's own production
+approval (billing info + their review, timeline unstated in their docs), a business/account action only
+the project owner can take.

data/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for considering a contribution to `spree_uber_direct`.
+
+## Getting set up
+
+```bash
+bundle install
+bundle exec rake test_app   # generates spec/dummy, the Rails app specs run against
+bundle exec rspec
+```
+
+## Making a change
+
+1. Open an issue first for anything beyond a small fix, so the approach can be discussed before
+   you put time into it.
+2. Add or update specs alongside any behavior change — `bundle exec rspec` should stay green.
+3. Keep decorators as a last resort (see the main README's customization pattern order); prefer
+   Spree's Events/Subscribers or Dependencies mechanisms where they fit.
+4. Open a pull request describing what changed and why.
+
+## Releasing (maintainers)
+
+```bash
+bundle exec gem bump --version [major|minor|patch] -t -m "Release v%s"
+bundle exec gem release
+```
+
+See the [gem-release README](https://github.com/svenfuchs/gem-release) for more options.

data/Gemfile

@@ -0,0 +1,27 @@
+source 'https://rubygems.org'
+
+gem 'rails-controller-testing'
+
+# Pinned to the released 5.6.x line (matching spree_host), same rationale as
+# spree_square's and spree_doordash's Gemfiles.
+spree_opts = if ENV['SPREE_PATH']
+                { 'path': ENV['SPREE_PATH'] }
+             else
+                '~> 5.6.0'
+             end
+gem 'spree', spree_opts
+gem 'spree_admin', spree_opts
+
+gem 'spree_dev_tools', '>= 0.6.0.rc1'
+
+if ENV['DB'] == 'mysql'
+  gem 'mysql2'
+elsif ENV['DB'] == 'postgres'
+  gem 'pg'
+else
+  gem 'sqlite3'
+end
+
+gem 'propshaft'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Amit Solanki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# SpreeUberDirect
+
+Dispatches completed [Spree Commerce](https://spreecommerce.org) orders as [Uber Direct](https://developer.uber.com/docs/deliveries/overview)
+deliveries — live delivery-fee quoting during checkout, dispatch on order completion, and delivery
+status synced back via webhooks.
+
+A second, independent delivery provider alongside [`spree_doordash`](https://github.com/amitkssolanki/spree_doordash)
+— both extensions add their own `Spree::ShippingMethod`, so a store can offer either, both, or
+neither, with zero coupling between them.
+
+## Status
+
+M1–M5 built and verified against a real Uber Direct Sandbox account end to end — real OAuth token,
+real quotes, a real dispatched delivery driven through Uber's "Robo Courier" test simulator from
+`pending` through `delivered`, both admin pages confirmed loading against real Postgres data. See
+[CHANGELOG.md](CHANGELOG.md) for the full milestone-by-milestone verification detail, including what
+was *not* live-tested (inbound webhook receiving — no public tunnel was set up). M6 (final spec
+polish/docs) and M7 (production go-live, gated on Uber's own approval) haven't started. Not yet
+tagged, pushed to a remote, or released.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'spree_uber_direct', git: 'https://github.com/amitkssolanki/spree_uber_direct.git', tag: 'v0.1.0'
+```
+
+Then:
+
+```bash
+bundle install
+bin/rails spree_uber_direct:install:migrations
+bin/rails db:migrate
+```
+
+## Setup
+
+1. Create a Direct account at [direct.uber.com](https://direct.uber.com) and log in with your Uber
+   account. Sandbox credentials (Client ID, Client Secret, Customer ID) are available immediately
+   under the Developer tab in Management — no approval needed for sandbox.
+2. In your Spree admin, go to **Uber Direct Connection** and paste the three sandbox values.
+3. Register a webhook endpoint in the Direct dashboard pointing at
+   `https://your-store.example.com/spree_uber_direct/webhooks/uber_direct`, then copy its signing
+   key into the same admin form.
+
+Production access requires providing billing information and Uber's approval — see
+[developer.uber.com/docs/deliveries/get-started](https://developer.uber.com/docs/deliveries/get-started).
+No fixed timeline is published for that approval; sandbox has none of that restriction.
+
+## Environment variables (alternative to the admin form, useful for scripting/rake tasks)
+
+```
+UBER_DIRECT_CLIENT_ID=
+UBER_DIRECT_CLIENT_SECRET=
+UBER_DIRECT_CUSTOMER_ID=
+UBER_DIRECT_ENVIRONMENT=sandbox
+```
+
+## Testing
+
+```bash
+bundle install
+bundle exec rake test_app
+bundle exec rspec
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

data/Rakefile

@@ -0,0 +1,23 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+require 'spree/testing_support/extension_rake'
+
+RSpec::Core::RakeTask.new
+
+task :default do
+  if Dir['spec/dummy'].empty?
+    Rake::Task[:test_app].invoke
+    Dir.chdir('../../')
+  end
+  Rake::Task[:spec].invoke
+end
+
+desc 'Generates a dummy app for testing'
+task :test_app do
+  ENV['LIB_NAME'] = 'spree_uber_direct'
+  Rake::Task['extension:test_app'].execute(
+    install_admin: true
+  )
+end

data/app/controllers/spree/admin/uber_direct_credentials_controller.rb

@@ -0,0 +1,52 @@
+module Spree
+  module Admin
+    # Plain credential-entry form for the current store's Uber Direct
+    # sandbox/production OAuth application — not a "Connect" redirect dance.
+    # An admin creates the application in the Direct dashboard
+    # (direct.uber.com) once and pastes the values in here directly
+    # (encrypted at rest — see SpreeUberDirect::Credential). Same static-form
+    # convention as spree_doordash's own credentials controller, even though
+    # the underlying auth is OAuth2 under the hood (client_credentials, not
+    # an authorization-code redirect).
+    class UberDirectCredentialsController < Spree::Admin::BaseController
+      def show
+        @credential = SpreeUberDirect::Credential.find_or_initialize_by(store: current_store)
+      end
+
+      def update
+        @credential = SpreeUberDirect::Credential.find_or_initialize_by(store: current_store)
+
+        if @credential.update(credential_params)
+          flash[:success] = Spree.t(:uber_direct_credential_saved, default: 'Uber Direct credentials saved.')
+        else
+          flash[:error] = @credential.errors.full_messages.to_sentence
+        end
+
+        redirect_to admin_uber_direct_credential_path
+      end
+
+      private
+
+      # Blank secret fields mean "leave unchanged" (the form always renders
+      # them empty and never echoes the current value back) — submitting an
+      # actually-blank value would otherwise silently overwrite a working
+      # credential with an empty string on every save. Also clears the
+      # cached access token whenever client_id/client_secret actually
+      # change, so a rotated secret takes effect on the very next API call
+      # instead of failing against the old token until it naturally expires.
+      def credential_params
+        permitted = params.require(:spree_uber_direct_credential).permit(
+          :client_id, :client_secret, :customer_id, :webhook_signing_secret, :uber_environment
+        )
+        %i[client_secret webhook_signing_secret].each do |field|
+          permitted.delete(field) if permitted[field].blank?
+        end
+        if permitted[:client_id].present? || permitted[:client_secret].present?
+          permitted[:access_token] = nil
+          permitted[:access_token_expires_at] = nil
+        end
+        permitted
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/uber_direct_delivery_mappings_controller.rb

@@ -0,0 +1,12 @@
+module Spree
+  module Admin
+    # Read-only support/diagnostic view — no create/edit/destroy, this is
+    # visibility into what spree_uber_direct has already done, not a place
+    # to change it. See config/routes.rb (only: [:index]).
+    class UberDirectDeliveryMappingsController < ResourceController
+      def model_class
+        SpreeUberDirect::DeliveryMapping
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/uber_direct_webhook_events_controller.rb

@@ -0,0 +1,10 @@
+module Spree
+  module Admin
+    # Read-only support/diagnostic view — same shape as UberDirectDeliveryMappingsController.
+    class UberDirectWebhookEventsController < ResourceController
+      def model_class
+        SpreeUberDirect::WebhookEvent
+      end
+    end
+  end
+end

data/app/controllers/spree_uber_direct/webhooks_controller.rb

@@ -0,0 +1,112 @@
+module SpreeUberDirect
+  # Receives Uber Direct webhook notifications. HMAC-verified (see
+  # SpreeUberDirect::WebhookVerifier) rather than DoorDash's Basic-Auth
+  # string-echo. Does the least possible work synchronously: verify,
+  # record, ack, hand off to a job — same shape as every sibling
+  # WebhooksController in this codebase.
+  class WebhooksController < ActionController::Base
+    # Explicit, not just `skip_before_action :verify_authenticity_token` —
+    # this controller doesn't inherit the host app's ApplicationController,
+    # so a static analyzer (Brakeman) correctly flags it as never actually
+    # configured either way — same precedent as spree_doordash's and
+    # spree_square's own WebhooksController.
+    protect_from_forgery with: :null_session
+
+    def create
+      credential = SpreeUberDirect::Credential.find_by(store: Spree::Store.default)
+      raw_body = request.raw_post
+
+      unless SpreeUberDirect::WebhookVerifier.valid?(
+        signature_header: request.headers['x-uber-signature'],
+        raw_body: raw_body,
+        signing_secret: credential&.webhook_signing_secret
+      )
+        Rails.logger.warn('[SpreeUberDirect] webhook signature verification failed')
+        return head :unauthorized
+      end
+
+      payload = JSON.parse(raw_body)
+
+      # Uber's dashboard lets a webhook subscribe to three event kinds on
+      # this one endpoint: `event.delivery_status` (the only one with a
+      # `status` field — confirmed live), `event.courier_update` (a
+      # courier GPS ping fired every 20s once a courier is assigned — no
+      # `status` field, confirmed live), and `event.refund_request` (fired
+      # when a refund is requested — no `status` field either, confirmed
+      # directly against Uber's own webhook payload docs). Unlike a
+      # courier ping, a refund notification carries real, unrecoverable
+      # data (data.id, currency_code, total_partner_refund,
+      # total_uber_refund, refund_fees, refund_order_items) — worth a
+      # durable record even with no consumer yet, so it's persisted to its
+      # own RefundEvent table before falling into the generic
+      # blank-status drop below.
+      if payload['kind'] == 'event.refund_request'
+        find_or_log_refund_event(raw_body, payload)
+        return head :ok
+      end
+
+      # WebhookEvent's `status` column is specifically Uber's *delivery*
+      # status (see its own model comment) and requires presence, so
+      # acknowledge and drop anything else that doesn't carry one rather
+      # than letting it fail validation and surface as a 404 to Uber's
+      # webhook delivery system — a courier-location ping needs no
+      # processing from this extension today.
+      if payload['status'].blank?
+        Rails.logger.debug { "[SpreeUberDirect] dropping webhook with no status (kind=#{payload['kind']}, id=#{payload['id']})" }
+        return head :ok
+      end
+
+      event = find_or_log_event(raw_body, payload)
+      SpreeUberDirect::DeliveryWebhookJob.perform_later(event.id) if event.previously_new_record?
+
+      head :ok
+    rescue JSON::ParserError
+      head :bad_request
+    end
+
+    private
+
+    def find_or_log_event(raw_body, payload)
+      SpreeUberDirect::WebhookEvent.find_or_create_by!(
+        delivery_id: payload['delivery_id'],
+        status: payload['status'],
+        payload_digest: SpreeUberDirect::WebhookEvent.digest(raw_body)
+      ) do |event|
+        event.payload = payload
+      end
+    rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid
+      # Lost a race with a concurrent duplicate delivery — the row exists
+      # now either way, and it's already being (or has been) processed once.
+      SpreeUberDirect::WebhookEvent.find_by!(
+        delivery_id: payload['delivery_id'],
+        status: payload['status'],
+        payload_digest: SpreeUberDirect::WebhookEvent.digest(raw_body)
+      )
+    end
+
+    def find_or_log_refund_event(raw_body, payload)
+      digest = SpreeUberDirect::RefundEvent.digest(raw_body)
+
+      SpreeUberDirect::RefundEvent.find_or_create_by!(
+        delivery_id: payload['delivery_id'],
+        payload_digest: digest
+      ) do |event|
+        event.payload = payload
+      end
+    rescue ActiveRecord::RecordNotUnique
+      # Lost a race with a concurrent duplicate delivery — the row exists
+      # now either way.
+      SpreeUberDirect::RefundEvent.find_by(delivery_id: payload['delivery_id'], payload_digest: digest)
+    rescue ActiveRecord::RecordInvalid => e
+      # A payload we genuinely can't persist (e.g. no delivery_id at all)
+      # — log loudly so the drop stays traceable, but still ack. A
+      # refund notification that can't even be stored shouldn't turn
+      # into a 4xx/5xx retry storm against Uber's webhook delivery
+      # system; Uber would just keep resending the identical payload.
+      Rails.logger.error(
+        "[SpreeUberDirect] failed to persist refund_request webhook: #{e.message} (id=#{payload['id']})"
+      )
+      nil
+    end
+  end
+end

data/app/jobs/spree_uber_direct/base_job.rb

@@ -0,0 +1,5 @@
+module SpreeUberDirect
+  class BaseJob < Spree::BaseJob
+    queue_as SpreeUberDirect.queue
+  end
+end

data/app/jobs/spree_uber_direct/delivery_dispatch_job.rb

@@ -0,0 +1,21 @@
+module SpreeUberDirect
+  # A failed dispatch is the worst failure mode in this whole extension —
+  # payment already taken, kitchen already has the ticket (spree_square's
+  # own push is independent), but no one is actually coming to pick it up.
+  # Same retry/dead-letter/Alerting shape as SpreeDoordash::DeliveryDispatchJob.
+  class DeliveryDispatchJob < BaseJob
+    retry_on StandardError, wait: :polynomially_longer, attempts: 5 do |job, error|
+      order = Spree::Order.find_by(id: job.arguments.first)
+      SpreeUberDirect::DeliveryMapping.find_or_initialize_by(order: order).mark_failed!(error) if order
+      SpreeUberDirect::Alerting.capture(
+        error,
+        context: { area: 'delivery_dispatch', order_number: order&.number }
+      )
+    end
+
+    def perform(order_id)
+      order = Spree::Order.find(order_id)
+      SpreeUberDirect::DeliveryDispatcher.call(order)
+    end
+  end
+end

data/app/jobs/spree_uber_direct/delivery_webhook_job.rb

@@ -0,0 +1,17 @@
+module SpreeUberDirect
+  # Applies one already-verified, already-deduplicated Uber Direct webhook
+  # event to the order it's mapped to. Same retry/dead-letter/Alerting
+  # shape as every other webhook-handling job in this codebase.
+  class DeliveryWebhookJob < BaseJob
+    retry_on StandardError, wait: :polynomially_longer, attempts: 5 do |job, error|
+      SpreeUberDirect::WebhookEvent.find_by(id: job.arguments.first)&.mark_failed!(error)
+      SpreeUberDirect::Alerting.capture(error, context: 'delivery_webhook')
+    end
+
+    def perform(webhook_event_id)
+      event = SpreeUberDirect::WebhookEvent.find(webhook_event_id)
+      SpreeUberDirect::DeliveryStatusMapper.call(event.payload)
+      event.mark_processed!
+    end
+  end
+end