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>

test/simpleshop_theme/webhooks_test.exs

@@ -132,4 +132,145 @@ defmodule SimpleshopTheme.WebhooksTest do
                })
     end
   end
+
+  # =============================================================================
+  # Printful events
+  # =============================================================================
+
+  describe "handle_printful_event/2 — product events" do
+    setup do
+      conn = provider_connection_fixture(%{provider_type: "printful"})
+      {:ok, printful_connection: conn}
+    end
+
+    test "product_updated triggers sync", %{printful_connection: _conn} do
+      assert {:ok, %Oban.Job{}} =
+               Webhooks.handle_printful_event("product_updated", %{})
+    end
+
+    test "product_synced triggers sync", %{printful_connection: _conn} do
+      assert {:ok, %Oban.Job{}} =
+               Webhooks.handle_printful_event("product_synced", %{})
+    end
+
+    test "product_deleted with sync_product id triggers delete" do
+      assert {:ok, %Oban.Job{}} =
+               Webhooks.handle_printful_event("product_deleted", %{
+                 "sync_product" => %{"id" => 12345}
+               })
+    end
+
+    test "product_deleted without id triggers full sync" do
+      provider_connection_fixture(%{provider_type: "printful"})
+
+      assert {:ok, %Oban.Job{}} =
+               Webhooks.handle_printful_event("product_deleted", %{})
+    end
+
+    test "unknown event returns ok" do
+      assert :ok = Webhooks.handle_printful_event("stock_updated", %{})
+    end
+
+    test "returns error when no printful connection" do
+      # Delete the printful connection created in setup
+      import Ecto.Query
+
+      from(pc in SimpleshopTheme.Products.ProviderConnection,
+        where: pc.provider_type == "printful"
+      )
+      |> SimpleshopTheme.Repo.delete_all()
+
+      assert {:error, :no_connection} =
+               Webhooks.handle_printful_event("product_updated", %{})
+    end
+  end
+
+  describe "handle_printful_event/2 — order events" do
+    setup do
+      provider_connection_fixture(%{provider_type: "printful"})
+      :ok
+    end
+
+    test "package_shipped sets tracking and shipped_at" do
+      {order, _v, _p, _c} = submitted_order_fixture()
+
+      assert {:ok, updated} =
+               Webhooks.handle_printful_event("package_shipped", %{
+                 "order" => %{"external_id" => order.order_number},
+                 "shipment" => %{
+                   "tracking_number" => "PF-TRACK-001",
+                   "tracking_url" => "https://tracking.printful.com/PF-TRACK-001"
+                 }
+               })
+
+      assert updated.fulfilment_status == "shipped"
+      assert updated.tracking_number == "PF-TRACK-001"
+      assert updated.tracking_url == "https://tracking.printful.com/PF-TRACK-001"
+      assert updated.shipped_at != nil
+    end
+
+    test "order_failed sets failed status" do
+      {order, _v, _p, _c} = submitted_order_fixture()
+
+      assert {:ok, updated} =
+               Webhooks.handle_printful_event("order_failed", %{
+                 "order" => %{"external_id" => order.order_number},
+                 "reason" => "Out of stock"
+               })
+
+      assert updated.fulfilment_status == "failed"
+      assert updated.fulfilment_error == "Out of stock"
+    end
+
+    test "order_failed with no reason uses default message" do
+      {order, _v, _p, _c} = submitted_order_fixture()
+
+      assert {:ok, updated} =
+               Webhooks.handle_printful_event("order_failed", %{
+                 "order" => %{"external_id" => order.order_number}
+               })
+
+      assert updated.fulfilment_error == "Order failed at Printful"
+    end
+
+    test "order_canceled sets cancelled status" do
+      {order, _v, _p, _c} = submitted_order_fixture()
+
+      assert {:ok, updated} =
+               Webhooks.handle_printful_event("order_canceled", %{
+                 "order" => %{"external_id" => order.order_number}
+               })
+
+      assert updated.fulfilment_status == "cancelled"
+    end
+
+    test "package_shipped with external_id at top level" do
+      {order, _v, _p, _c} = submitted_order_fixture()
+
+      assert {:ok, updated} =
+               Webhooks.handle_printful_event("package_shipped", %{
+                 "external_id" => order.order_number,
+                 "shipment" => %{
+                   "tracking_number" => "PF-TRACK-002"
+                 }
+               })
+
+      assert updated.fulfilment_status == "shipped"
+      assert updated.tracking_number == "PF-TRACK-002"
+    end
+
+    test "order event with unknown external_id returns error" do
+      assert {:error, :order_not_found} =
+               Webhooks.handle_printful_event("package_shipped", %{
+                 "order" => %{"external_id" => "SS-000000-NOPE"}
+               })
+    end
+
+    test "order event with no external_id returns error" do
+      assert {:error, :missing_external_id} =
+               Webhooks.handle_printful_event("package_shipped", %{
+                 "order" => %{"id" => 12345}
+               })
+    end
+  end
 end

test/simpleshop_theme_web/controllers/webhook_controller_test.exs

@@ -98,4 +98,81 @@ defmodule SimpleshopThemeWeb.WebhookControllerTest do
     :crypto.mac(:hmac, :sha256, secret, body)
     |> Base.encode16(case: :lower)
   end
+
+  describe "POST /webhooks/printful" do
+    @printful_secret "printful_test_secret_456"
+
+    setup do
+      _conn =
+        provider_connection_fixture(%{
+          provider_type: "printful",
+          config: %{"store_id" => "99999", "webhook_secret" => @printful_secret}
+        })
+
+      :ok
+    end
+
+    test "returns 401 without token", %{conn: conn} do
+      conn =
+        conn
+        |> put_req_header("content-type", "application/json")
+        |> post(~p"/webhooks/printful", %{type: "product_updated"})
+
+      assert json_response(conn, 401)["error"] == "Invalid token"
+    end
+
+    test "returns 401 with wrong token", %{conn: conn} do
+      conn =
+        conn
+        |> put_req_header("content-type", "application/json")
+        |> put_req_header("x-pf-webhook-token", "wrong_token")
+        |> post(~p"/webhooks/printful", %{type: "product_updated"})
+
+      assert json_response(conn, 401)["error"] == "Invalid token"
+    end
+
+    test "accepts valid token via header", %{conn: conn} do
+      conn =
+        conn
+        |> put_req_header("content-type", "application/json")
+        |> put_req_header("x-pf-webhook-token", @printful_secret)
+        |> post(~p"/webhooks/printful", %{type: "product_updated", data: %{}})
+
+      assert json_response(conn, 200)["status"] == "ok"
+    end
+
+    test "accepts valid token via query param", %{conn: conn} do
+      conn =
+        conn
+        |> put_req_header("content-type", "application/json")
+        |> post(~p"/webhooks/printful?token=#{@printful_secret}", %{
+          type: "product_updated",
+          data: %{}
+        })
+
+      assert json_response(conn, 200)["status"] == "ok"
+    end
+
+    test "handles unknown event gracefully", %{conn: conn} do
+      conn =
+        conn
+        |> put_req_header("content-type", "application/json")
+        |> put_req_header("x-pf-webhook-token", @printful_secret)
+        |> post(~p"/webhooks/printful", %{type: "unknown_event", data: %{}})
+
+      assert json_response(conn, 200)["status"] == "ok"
+    end
+
+    test "returns 401 when no webhook secret configured", %{conn: conn} do
+      SimpleshopTheme.Repo.delete_all(SimpleshopTheme.Products.ProviderConnection)
+
+      conn =
+        conn
+        |> put_req_header("content-type", "application/json")
+        |> put_req_header("x-pf-webhook-token", @printful_secret)
+        |> post(~p"/webhooks/printful", %{type: "product_updated"})
+
+      assert json_response(conn, 401)["error"] == "Invalid token"
+    end
+  end
 end