add Printful webhook endpoint with token verification

New POST /webhooks/printful route with VerifyPrintfulWebhook plug
(shared secret token via header or query param). Handles package_shipped,
order_failed, order_canceled, product_updated, product_synced, and
product_deleted events. Webhook registration via Printful v2 API with
token appended to URL. 19 new tests (819 total).

Also marks task #28 as done — Printful sync products already include
preview mockup images handled by the existing ImageDownloadWorker
pipeline.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lib/simpleshop_theme/providers/printful.ex

@@ -504,6 +504,69 @@ defmodule SimpleshopTheme.Providers.Printful do
     }
   end
 
+  # =============================================================================
+  # Webhooks
+  # =============================================================================
+
+  @webhook_events [
+    "package_shipped",
+    "package_returned",
+    "order_failed",
+    "order_canceled",
+    "product_synced",
+    "product_updated",
+    "product_deleted"
+  ]
+
+  @doc """
+  Registers webhooks with Printful for this store.
+
+  The webhook URL should include a token query param for verification,
+  e.g. `https://example.com/webhooks/printful?token=SECRET`.
+  """
+  def register_webhooks(%ProviderConnection{config: config} = conn, webhook_url) do
+    store_id = config["store_id"]
+    secret = config["webhook_secret"]
+
+    cond do
+      is_nil(store_id) ->
+        {:error, :no_store_id}
+
+      is_nil(secret) or secret == "" ->
+        {:error, :no_webhook_secret}
+
+      true ->
+        with api_key when is_binary(api_key) <- ProviderConnection.get_api_key(conn),
+             :ok <- set_credentials(api_key, store_id) do
+          url_with_token = append_token(webhook_url, secret)
+          Client.setup_webhooks(url_with_token, @webhook_events)
+        else
+          nil -> {:error, :no_api_key}
+        end
+    end
+  end
+
+  @doc """
+  Lists currently registered webhooks for this store.
+  """
+  def list_webhooks(%ProviderConnection{config: config} = conn) do
+    store_id = config["store_id"]
+
+    with api_key when is_binary(api_key) <- ProviderConnection.get_api_key(conn),
+         :ok <- set_credentials(api_key, store_id) do
+      Client.get_webhooks()
+    else
+      nil -> {:error, :no_api_key}
+    end
+  end
+
+  defp append_token(url, token) do
+    uri = URI.parse(url)
+    params = URI.decode_query(uri.query || "")
+    query = URI.encode_query(Map.put(params, "token", token))
+    URI.to_string(%{uri | query: query})
+  end
+
   # =============================================================================
   # Helpers
   # =============================================================================

lib/simpleshop_theme/webhooks.ex

@@ -81,7 +81,85 @@ defmodule SimpleshopTheme.Webhooks do
     :ok
   end
 
-  # --- Private helpers ---
+  # =============================================================================
+  # Printful events
+  # =============================================================================
+
+  @doc """
+  Handles a Printful webhook event.
+
+  Returns :ok or {:ok, result} on success, {:error, reason} on failure.
+  """
+
+  # --- Order events ---
+
+  def handle_printful_event("package_shipped", data) do
+    with {:ok, order} <- find_printful_order(data) do
+      shipment = extract_printful_shipment(data)
+
+      {:ok, updated} =
+        Orders.update_fulfilment(order, %{
+          fulfilment_status: "shipped",
+          provider_status: "shipped",
+          tracking_number: shipment.tracking_number,
+          tracking_url: shipment.tracking_url,
+          shipped_at: DateTime.utc_now() |> DateTime.truncate(:second)
+        })
+
+      OrderNotifier.deliver_shipping_notification(updated)
+      {:ok, updated}
+    end
+  end
+
+  def handle_printful_event("order_failed", data) do
+    with {:ok, order} <- find_printful_order(data) do
+      Orders.update_fulfilment(order, %{
+        fulfilment_status: "failed",
+        provider_status: "failed",
+        fulfilment_error: data["reason"] || "Order failed at Printful"
+      })
+    end
+  end
+
+  def handle_printful_event("order_canceled", data) do
+    with {:ok, order} <- find_printful_order(data) do
+      Orders.update_fulfilment(order, %{
+        fulfilment_status: "cancelled",
+        provider_status: "canceled"
+      })
+    end
+  end
+
+  # --- Product events ---
+
+  def handle_printful_event("product_updated", _data) do
+    enqueue_printful_sync()
+  end
+
+  def handle_printful_event("product_synced", _data) do
+    enqueue_printful_sync()
+  end
+
+  def handle_printful_event("product_deleted", %{"sync_product" => %{"id" => product_id}}) do
+    ProductDeleteWorker.enqueue(to_string(product_id))
+  end
+
+  def handle_printful_event("product_deleted", _data) do
+    enqueue_printful_sync()
+  end
+
+  # --- Catch-all ---
+
+  def handle_printful_event(event_type, _data) do
+    Logger.info("Ignoring unhandled Printful event: #{event_type}")
+    :ok
+  end
+
+  # =============================================================================
+  # Private helpers
+  # =============================================================================
+
+  # --- Printify helpers ---
 
   defp enqueue_product_sync do
     case Products.get_provider_connection_by_type("printify") do
@@ -90,7 +168,6 @@ defmodule SimpleshopTheme.Webhooks do
     end
   end
 
-  # Printify order webhooks include external_id (our order_number) in the resource
   defp find_order_from_resource(%{"external_id" => external_id}) when is_binary(external_id) do
     case Orders.get_order_by_number(external_id) do
       nil ->
@@ -116,4 +193,50 @@ defmodule SimpleshopTheme.Webhooks do
       tracking_url: shipment["tracking_url"]
     }
   end
+
+  # --- Printful helpers ---
+
+  defp enqueue_printful_sync do
+    case Products.get_provider_connection_by_type("printful") do
+      nil -> {:error, :no_connection}
+      conn -> ProductSyncWorker.enqueue(conn.id)
+    end
+  end
+
+  # Printful order webhooks include external_id in the order data
+  defp find_printful_order(%{"order" => %{"external_id" => ext_id}})
+       when is_binary(ext_id) and ext_id != "" do
+    find_order_by_external_id(ext_id)
+  end
+
+  # Fallback: look for external_id at top level
+  defp find_printful_order(%{"external_id" => ext_id})
+       when is_binary(ext_id) and ext_id != "" do
+    find_order_by_external_id(ext_id)
+  end
+
+  defp find_printful_order(data) do
+    Logger.warning("Printful order webhook: can't find external_id in #{inspect(data)}")
+    {:error, :missing_external_id}
+  end
+
+  defp find_order_by_external_id(external_id) do
+    case Orders.get_order_by_number(external_id) do
+      nil ->
+        Logger.warning("Order webhook: no order found for external_id=#{external_id}")
+        {:error, :order_not_found}
+
+      order ->
+        {:ok, order}
+    end
+  end
+
+  defp extract_printful_shipment(data) do
+    shipment = data["shipment"] || %{}
+
+    %{
+      tracking_number: shipment["tracking_number"],
+      tracking_url: shipment["tracking_url"]
+    }
+  end
 end