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

lib/simpleshop_theme_web/controllers/webhook_controller.ex

@@ -33,4 +33,34 @@ defmodule SimpleshopThemeWeb.WebhookController do
         json(conn, %{status: "ok"})
     end
   end
+
+  @doc """
+  Receives Printful webhook events.
+
+  Events:
+  - package_shipped - Package has been shipped
+  - order_failed - Order processing failed
+  - order_canceled - Order was canceled
+  - product_updated - Sync product was updated
+  - product_deleted - Sync product was deleted
+  """
+  def printful(conn, params) do
+    event_type = params["type"]
+    data = params["data"] || %{}
+
+    Logger.info("Received Printful webhook: #{event_type}")
+
+    case Webhooks.handle_printful_event(event_type, data) do
+      :ok ->
+        json(conn, %{status: "ok"})
+
+      {:ok, _} ->
+        json(conn, %{status: "ok"})
+
+      {:error, reason} ->
+        Logger.warning("Printful webhook handling failed: #{inspect(reason)}")
+        # Return 200 to prevent Printful retrying
+        json(conn, %{status: "ok"})
+    end
+  end
 end

lib/simpleshop_theme_web/plugs/verify_printful_webhook.ex

@@ -0,0 +1,67 @@
+defmodule SimpleshopThemeWeb.Plugs.VerifyPrintfulWebhook do
+  @moduledoc """
+  Verifies Printful webhook requests using a shared secret token.
+
+  Checks the `webhook_secret` stored in the Printful provider connection
+  config against the `X-PF-Webhook-Token` header (or `token` query param
+  as fallback). Can be upgraded to HMAC signature verification once the
+  exact Printful signing format is confirmed.
+
+  Expects raw body cached in conn.assigns[:raw_body] (via CacheRawBody).
+  """
+
+  import Plug.Conn
+  require Logger
+
+  alias SimpleshopTheme.Products
+
+  def init(opts), do: opts
+
+  def call(conn, _opts) do
+    with {:ok, token} <- get_token(conn),
+         {:ok, secret} <- get_webhook_secret(),
+         :ok <- verify_token(token, secret) do
+      conn
+    else
+      {:error, reason} ->
+        Logger.warning("Printful webhook verification failed: #{reason}")
+
+        conn
+        |> put_resp_content_type("application/json")
+        |> send_resp(401, Jason.encode!(%{error: "Invalid token"}))
+        |> halt()
+    end
+  end
+
+  defp get_token(conn) do
+    # Check header first, then query param
+    case get_req_header(conn, "x-pf-webhook-token") do
+      [token] when token != "" ->
+        {:ok, token}
+
+      _ ->
+        case conn.query_params["token"] || conn.params["token"] do
+          token when is_binary(token) and token != "" -> {:ok, token}
+          _ -> {:error, :missing_token}
+        end
+    end
+  end
+
+  defp get_webhook_secret do
+    case Products.get_provider_connection_by_type("printful") do
+      %{config: %{"webhook_secret" => secret}} when is_binary(secret) and secret != "" ->
+        {:ok, secret}
+
+      _ ->
+        {:error, :no_webhook_secret}
+    end
+  end
+
+  defp verify_token(token, secret) do
+    if Plug.Crypto.secure_compare(token, secret) do
+      :ok
+    else
+      {:error, :token_mismatch}
+    end
+  end
+end

lib/simpleshop_theme_web/router.ex

@@ -24,6 +24,10 @@ defmodule SimpleshopThemeWeb.Router do
     plug SimpleshopThemeWeb.Plugs.VerifyPrintifyWebhook
   end
 
+  pipeline :printful_webhook do
+    plug SimpleshopThemeWeb.Plugs.VerifyPrintfulWebhook
+  end
+
   pipeline :shop do
     plug :put_root_layout, html: {SimpleshopThemeWeb.Layouts, :shop_root}
     plug SimpleshopThemeWeb.Plugs.LoadTheme
@@ -101,6 +105,12 @@ defmodule SimpleshopThemeWeb.Router do
     post "/printify", WebhookController, :printify
   end
 
+  scope "/webhooks", SimpleshopThemeWeb do
+    pipe_through [:api, :printful_webhook]
+
+    post "/printful", WebhookController, :printful
+  end
+
   scope "/webhooks", SimpleshopThemeWeb do
     pipe_through [:api]