From 06d6b0b29ceda577de47f7954b3339a7d1505dab Mon Sep 17 00:00:00 2001
From: Jakob Schweigert <jaschweigert@hotmail.de>
Date: Thu, 11 Jun 2026 14:08:00 +0200
Subject: [PATCH] Add game webhooks for turn and phase changes

---
 WEBSITE_INTEGRATION.md                        |  49 ++
 .../agenda/AgendaResolveButtonHandler.java    |   4 +
 .../ChecksAndBalancesButtonHandler.java       |   3 +
 .../handlers/edict/EdictPhaseHandler.java     |   3 +
 .../PickStrategyCardButtonHandler.java        |   3 +
 .../interactions/commands/player/SCPick.java  |   4 +
 .../commands/player/SCUnpick.java             |   3 +
 src/main/java/ti4/helpers/AgendaHelper.java   |   5 +
 src/main/java/ti4/helpers/StatusHelper.java   |   3 +
 .../helpers/thundersedge/TeHelperTechs.java   |   3 +
 .../ti4/service/game/StartPhaseService.java   |   9 +
 .../strategycard/PickStrategyCardService.java |   4 +
 .../ti4/service/turn/StartTurnService.java    |   2 +
 .../service/webhook/GameWebhookEventType.java |  51 ++
 .../service/webhook/GameWebhookNotifier.java  |  81 +++
 .../webhook/GameWebhookNotifierFacade.java    |  41 ++
 .../service/webhook/GameWebhookPayload.java   |  15 +
 .../webhook/WebhookDispatchService.java       |  96 ++++
 .../api/webhook/GameWebhookApiController.java |  64 +++
 .../webhook/GameWebhookEventTypeResponse.java |  27 +
 .../GameWebhookSubscriptionRequest.java       |   5 +
 .../service/webhook/GameWebhookEntity.java    |  33 ++
 .../webhook/GameWebhookRepository.java        |  14 +
 .../GameWebhookSubscriptionService.java       | 122 +++++
 .../service/webhook/WebhookUserEntity.java    |  33 ++
 .../webhook/WebhookUserRepository.java        |   9 +
 .../webhook/GameWebhookNotifierTest.java      |  99 ++++
 .../webhook/WebhookDispatchServiceTest.java   |  27 +
 .../webhook/GameWebhookApiControllerTest.java | 477 ++++++++++++++++++
 29 files changed, 1289 insertions(+)
 create mode 100644 src/main/java/ti4/service/webhook/GameWebhookEventType.java
 create mode 100644 src/main/java/ti4/service/webhook/GameWebhookNotifier.java
 create mode 100644 src/main/java/ti4/service/webhook/GameWebhookNotifierFacade.java
 create mode 100644 src/main/java/ti4/service/webhook/GameWebhookPayload.java
 create mode 100644 src/main/java/ti4/service/webhook/WebhookDispatchService.java
 create mode 100644 src/main/java/ti4/spring/api/webhook/GameWebhookApiController.java
 create mode 100644 src/main/java/ti4/spring/api/webhook/GameWebhookEventTypeResponse.java
 create mode 100644 src/main/java/ti4/spring/api/webhook/GameWebhookSubscriptionRequest.java
 create mode 100644 src/main/java/ti4/spring/service/webhook/GameWebhookEntity.java
 create mode 100644 src/main/java/ti4/spring/service/webhook/GameWebhookRepository.java
 create mode 100644 src/main/java/ti4/spring/service/webhook/GameWebhookSubscriptionService.java
 create mode 100644 src/main/java/ti4/spring/service/webhook/WebhookUserEntity.java
 create mode 100644 src/main/java/ti4/spring/service/webhook/WebhookUserRepository.java
 create mode 100644 src/test/java/ti4/service/webhook/GameWebhookNotifierTest.java
 create mode 100644 src/test/java/ti4/service/webhook/WebhookDispatchServiceTest.java
 create mode 100644 src/test/java/ti4/spring/api/webhook/GameWebhookApiControllerTest.java

diff --git a/WEBSITE_INTEGRATION.md b/WEBSITE_INTEGRATION.md
index 8f45fe9bbe..ce985e37a1 100644
--- a/WEBSITE_INTEGRATION.md
+++ b/WEBSITE_INTEGRATION.md
@@ -2,6 +2,55 @@
 
 This document describes how the TI4 Map Generator Bot integrates with the AsyncTI4 website UI.
 
+## Game Webhooks
+
+Trusted external integrations can subscribe to non-FoW game changes without polling. Server operators create `webhook_user` rows with the callback URL and SHA-256 API key hash.
+
+Supported events:
+
+- `TURN_CHANGED`
+- `PHASE_CHANGED`
+
+Endpoints:
+
+- `GET /api/public/game/webhook/eventTypes` returns supported event names, trigger descriptions, delivery settings, and payload fields.
+- `PUT /api/public/game/{gameName}/webhook` with `X-API-Key` and JSON body:
+
+```json
+{ "eventTypes": ["TURN_CHANGED", "PHASE_CHANGED"] }
+```
+
+- `DELETE /api/public/game/{gameName}/webhook` with `X-API-Key`
+
+Example `TURN_CHANGED` payload:
+
+```json
+{
+  "gameName": "pbd1234",
+  "eventType": "TURN_CHANGED",
+  "phaseOfGame": "action",
+  "round": 5,
+  "activePlayerId": "123456789012345678",
+  "activeFaction": "arborec",
+  "timestamp": "2026-06-02T14:30:00Z"
+}
+```
+
+Example `PHASE_CHANGED` payload:
+
+```json
+{
+  "gameName": "pbd1234",
+  "eventType": "PHASE_CHANGED",
+  "previousPhaseOfGame": "strategy",
+  "phaseOfGame": "agenda",
+  "round": 4,
+  "timestamp": "2026-06-02T14:30:00Z"
+}
+```
+
+Delivery is asynchronous. Webhook failures never block game flow; transient failures may be retried once, and permanent 4xx failures are not retried.
+
 ## Image Asset Pipeline
 
 Game assets (faction banners, planet images, system tiles, etc.) are automatically uploaded to a CloudFront-backed S3 bucket and served to the website.
diff --git a/src/main/java/ti4/discord/interactions/buttons/handlers/agenda/AgendaResolveButtonHandler.java b/src/main/java/ti4/discord/interactions/buttons/handlers/agenda/AgendaResolveButtonHandler.java
index 121dea25f4..4e22de6222 100644
--- a/src/main/java/ti4/discord/interactions/buttons/handlers/agenda/AgendaResolveButtonHandler.java
+++ b/src/main/java/ti4/discord/interactions/buttons/handlers/agenda/AgendaResolveButtonHandler.java
@@ -70,6 +70,7 @@
 import ti4.service.info.SecretObjectiveInfoService;
 import ti4.service.leader.CommanderUnlockCheckService;
 import ti4.service.turn.StartTurnService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 @UtilityClass
 class AgendaResolveButtonHandler {
@@ -467,10 +468,13 @@ private static void sendNextStepUi(
                     + ", please use this buttons to proceed after fully resolving the agenda.";
             buttons = StartTurnService.getStartOfTurnButtons(executiveOrderPlayer, game, true, event);
             game.removeStoredValue("executiveOrder");
+            String previousPhaseOfGame = game.getPhaseOfGame();
             game.updateActivePlayer(executiveOrderPlayer);
             Player oldSpeaker = game.getPlayer(game.getStoredValue("oldSpeakerExecutiveOrder"));
             game.setSpeaker(oldSpeaker);
             game.setPhaseOfGame("action");
+            GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "action");
+            GameWebhookNotifierFacade.turnChanged(game);
             MessageHelper.sendMessageToChannelWithButtons(event.getChannel(), voteMessage, buttons);
         }
         if (!"action".equalsIgnoreCase(game.getPhaseOfGame())) {
diff --git a/src/main/java/ti4/discord/interactions/buttons/handlers/agenda/ChecksAndBalancesButtonHandler.java b/src/main/java/ti4/discord/interactions/buttons/handlers/agenda/ChecksAndBalancesButtonHandler.java
index ea245c94f6..abe8034bb3 100644
--- a/src/main/java/ti4/discord/interactions/buttons/handlers/agenda/ChecksAndBalancesButtonHandler.java
+++ b/src/main/java/ti4/discord/interactions/buttons/handlers/agenda/ChecksAndBalancesButtonHandler.java
@@ -15,6 +15,7 @@
 import ti4.message.MessageHelper;
 import ti4.service.game.StartPhaseService;
 import ti4.service.player.PlayerStatsService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 @UtilityClass
 class ChecksAndBalancesButtonHandler {
@@ -65,8 +66,10 @@ public static void resolvePt2ChecksNBalances(
             if (privatePlayer == null) {
                 privatePlayer = game.getRealPlayers().getFirst();
             }
+            String previousPhaseOfGame = game.getPhaseOfGame();
             game.setPhaseOfGame("strategy");
             game.updateActivePlayer(privatePlayer);
+            GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "strategy");
             MessageHelper.sendMessageToChannelWithButtons(
                     privatePlayer.getCorrectChannel(),
                     privatePlayer.getRepresentationUnfogged()
diff --git a/src/main/java/ti4/discord/interactions/buttons/handlers/edict/EdictPhaseHandler.java b/src/main/java/ti4/discord/interactions/buttons/handlers/edict/EdictPhaseHandler.java
index a0dd23222c..80d23ab0b3 100644
--- a/src/main/java/ti4/discord/interactions/buttons/handlers/edict/EdictPhaseHandler.java
+++ b/src/main/java/ti4/discord/interactions/buttons/handlers/edict/EdictPhaseHandler.java
@@ -15,6 +15,7 @@
 import ti4.message.MessageHelper;
 import ti4.model.AgendaModel;
 import ti4.model.DeckModel;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 @UtilityClass
 public class EdictPhaseHandler {
@@ -30,7 +31,9 @@ public List<String> getEdictDeck(Game game) {
 
     @ButtonHandler("edictPhase")
     public static void edictPhase(GenericInteractionCreateEvent event, Game game) {
+        String previousPhaseOfGame = game.getPhaseOfGame();
         game.setPhaseOfGame("agenda");
+        GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "agenda");
         List<String> edicts = getEdictDeck(game);
         List<Button> buttons = new ArrayList<>();
         List<MessageEmbed> embeds = new ArrayList<>();
diff --git a/src/main/java/ti4/discord/interactions/buttons/handlers/strategycard/PickStrategyCardButtonHandler.java b/src/main/java/ti4/discord/interactions/buttons/handlers/strategycard/PickStrategyCardButtonHandler.java
index 9409aa246e..092b1b5a77 100644
--- a/src/main/java/ti4/discord/interactions/buttons/handlers/strategycard/PickStrategyCardButtonHandler.java
+++ b/src/main/java/ti4/discord/interactions/buttons/handlers/strategycard/PickStrategyCardButtonHandler.java
@@ -27,6 +27,7 @@
 import ti4.service.leader.CommanderUnlockCheckService;
 import ti4.service.player.PlayerStatsService;
 import ti4.service.strategycard.PickStrategyCardService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 @UtilityClass
 public class PickStrategyCardButtonHandler {
@@ -188,8 +189,10 @@ public static void resolvePt2ChecksNBalances(
             if (privatePlayer == null) {
                 privatePlayer = game.getRealPlayers().getFirst();
             }
+            String previousPhaseOfGame = game.getPhaseOfGame();
             game.setPhaseOfGame("strategy");
             game.updateActivePlayer(privatePlayer);
+            GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "strategy");
             MessageHelper.sendMessageToChannelWithButtons(
                     privatePlayer.getCorrectChannel(),
                     privatePlayer.getRepresentationUnfogged()
diff --git a/src/main/java/ti4/discord/interactions/commands/player/SCPick.java b/src/main/java/ti4/discord/interactions/commands/player/SCPick.java
index 19a414cb0e..188bd661d1 100644
--- a/src/main/java/ti4/discord/interactions/commands/player/SCPick.java
+++ b/src/main/java/ti4/discord/interactions/commands/player/SCPick.java
@@ -20,6 +20,7 @@
 import ti4.service.game.StartPhaseService;
 import ti4.service.player.PlayerStatsService;
 import ti4.service.strategycard.PickStrategyCardService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 class SCPick extends GameStateSubcommand {
 
@@ -92,6 +93,7 @@ private static void secondHalfOfSCPick(
         }
 
         boolean nextCorrectPing = false;
+        String previousPhaseOfGame = game.getPhaseOfGame();
         Queue<Player> players = new ArrayDeque<>(activePlayers);
         while (players.iterator().hasNext() && player.isRealPlayer()) {
             Player currentPlayer = players.poll();
@@ -121,6 +123,7 @@ private static void secondHalfOfSCPick(
             game.updateActivePlayer(privatePlayer);
             if (!allPicked) {
                 game.setPhaseOfGame("strategy");
+                GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "strategy");
                 MessageHelper.sendMessageToChannelWithButtons(
                         privatePlayer.getPrivateChannel(),
                         "Use buttons to pick your strategy card.",
@@ -130,6 +133,7 @@ private static void secondHalfOfSCPick(
             if (!allPicked) {
                 game.updateActivePlayer(privatePlayer);
                 game.setPhaseOfGame("strategy");
+                GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "strategy");
                 PickStrategyCardService.checkForForcePickLastStratCard(event, privatePlayer, game, msgExtra);
             }
         }
diff --git a/src/main/java/ti4/discord/interactions/commands/player/SCUnpick.java b/src/main/java/ti4/discord/interactions/commands/player/SCUnpick.java
index a46cf77ce4..1db0839304 100644
--- a/src/main/java/ti4/discord/interactions/commands/player/SCUnpick.java
+++ b/src/main/java/ti4/discord/interactions/commands/player/SCUnpick.java
@@ -12,6 +12,7 @@
 import ti4.helpers.Constants;
 import ti4.helpers.Helper;
 import ti4.message.MessageHelper;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 class SCUnpick extends GameStateSubcommand {
 
@@ -34,8 +35,10 @@ public void execute(SlashCommandInteractionEvent event) {
         Player player = getPlayer();
         player.removeSC(scUnpicked);
         List<Button> scButtons = Helper.getRemainingSCButtons(game, player);
+        String previousPhaseOfGame = game.getPhaseOfGame();
         game.updateActivePlayer(player);
         game.setPhaseOfGame("strategy");
+        GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "strategy");
         MessageHelper.sendMessageToChannelWithButtons(
                 player.getCorrectChannel(), player.getRepresentation() + ", please pick a strategy card.", scButtons);
     }
diff --git a/src/main/java/ti4/helpers/AgendaHelper.java b/src/main/java/ti4/helpers/AgendaHelper.java
index 7723d19772..1371fd657d 100644
--- a/src/main/java/ti4/helpers/AgendaHelper.java
+++ b/src/main/java/ti4/helpers/AgendaHelper.java
@@ -75,6 +75,7 @@
 import ti4.service.unit.AddUnitService;
 import ti4.service.unit.CheckUnitContainmentService;
 import ti4.service.unit.DestroyUnitService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 @UtilityClass
 public final class AgendaHelper {
@@ -1864,7 +1865,9 @@ private static List<Button> getVoteButtonsVersion2(int minVote, int voteTotal) {
     }
 
     public static void startTheVoting(Game game) {
+        String previousPhaseOfGame = game.getPhaseOfGame();
         game.setPhaseOfGame("agendaVoting");
+        GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "agendaVoting");
         if (!game.getStoredValue("CommFormPreset").isEmpty()) {
             autoResolve(
                     null,
@@ -4012,7 +4015,9 @@ public static void revealAgenda(
         Integer uniqueID = discardAgendas.get(agendaID);
         boolean action = false;
         if (!"action".equalsIgnoreCase(game.getPhaseOfGame())) {
+            String previousPhaseOfGame = game.getPhaseOfGame();
             game.setPhaseOfGame("agendawaiting");
+            GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "agendawaiting");
             if (aCount == 1) {
                 GMService.logActivity(game, "**Agenda** Phase for Round " + game.getRound() + " started.", true);
                 FowCommunicationThreadService.checkAllCommThreads(game);
diff --git a/src/main/java/ti4/helpers/StatusHelper.java b/src/main/java/ti4/helpers/StatusHelper.java
index f8af11f419..1f896e1c6e 100644
--- a/src/main/java/ti4/helpers/StatusHelper.java
+++ b/src/main/java/ti4/helpers/StatusHelper.java
@@ -49,6 +49,7 @@
 import ti4.service.objectives.ScorePublicObjectiveService;
 import ti4.service.planet.EronousPlanetService;
 import ti4.service.turn.StartTurnService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 import ti4.settings.users.UserSettingsManager;
 
 @UtilityClass
@@ -153,7 +154,9 @@ public static void offerPreScoringButtons(Game game, Player player) {
     }
 
     public static void beginScoring(GenericInteractionCreateEvent event, Game game, MessageChannel gameChannel) {
+        String previousPhaseOfGame = game.getPhaseOfGame();
         game.setPhaseOfGame("statusScoring");
+        GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "statusScoring");
         game.setStoredValue("startTimeOfRound" + game.getRound() + "StatusScoring", System.currentTimeMillis() + "");
         GMService.logActivity(game, "**StatusScoring** Phase for Round " + game.getRound() + " started.", true);
         for (Player player : game.getRealPlayers()) {
diff --git a/src/main/java/ti4/helpers/thundersedge/TeHelperTechs.java b/src/main/java/ti4/helpers/thundersedge/TeHelperTechs.java
index 3d1b64d591..ab962d5865 100644
--- a/src/main/java/ti4/helpers/thundersedge/TeHelperTechs.java
+++ b/src/main/java/ti4/helpers/thundersedge/TeHelperTechs.java
@@ -41,6 +41,7 @@
 import ti4.service.regex.RegexService;
 import ti4.service.unit.DestroyUnitService;
 import ti4.service.unit.ParsedUnit;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 public final class TeHelperTechs {
 
@@ -583,7 +584,9 @@ public static void postExecutiveOrderButtons(GenericInteractionCreateEvent event
     @ButtonHandler("useExecutiveOrder_")
     private static void executiveOrder(ButtonInteractionEvent event, Game game, Player player, String buttonID) {
         game.setStoredValue("executiveOrder", player.getFaction());
+        String previousPhaseOfGame = game.getPhaseOfGame();
         game.setPhaseOfGame("agenda");
+        GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "agenda");
         boolean top = buttonID.contains("top");
 
         String msg = game.getPing() + " the " + buttonID.split("_")[1]
diff --git a/src/main/java/ti4/service/game/StartPhaseService.java b/src/main/java/ti4/service/game/StartPhaseService.java
index 1db6159b0f..1dac2aa0ab 100644
--- a/src/main/java/ti4/service/game/StartPhaseService.java
+++ b/src/main/java/ti4/service/game/StartPhaseService.java
@@ -72,6 +72,7 @@
 import ti4.service.planet.PlanetService;
 import ti4.service.strategycard.PickStrategyCardService;
 import ti4.service.turn.StartTurnService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 import ti4.settings.users.UserSettingsManager;
 
 @UtilityClass
@@ -83,7 +84,9 @@ public static void startPhase(GenericInteractionCreateEvent event, Game game, St
             case "voting", "agendaVoting" -> AgendaHelper.startTheVoting(game);
             case "shuffleDecks" -> game.shuffleDecks();
             case "agenda" -> {
+                String previousPhaseOfGame = game.getPhaseOfGame();
                 game.setPhaseOfGame("agenda");
+                GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "agenda");
                 Button flipAgenda = Buttons.blue("flip_agenda", "Flip Agenda");
                 List<Button> buttons = List.of(flipAgenda);
                 MessageHelper.sendMessageToChannelWithButtons(
@@ -529,8 +532,10 @@ public static void startStrategyPhase(GenericInteractionCreateEvent event, Game
             firstSCPicker = firstInPriorityOrder.get();
         }
         String message = firstSCPicker.getRepresentationUnfogged() + " is up to pick a strategy card.";
+        String previousPhaseOfGame = game.getPhaseOfGame();
         game.updateActivePlayer(firstSCPicker);
         game.setPhaseOfGame("strategy");
+        GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "strategy");
         GMService.logActivity(game, "**Strategy** Phase for Round " + game.getRound() + " started.", true);
         FowCommunicationThreadService.checkAllCommThreads(game);
         SpinService.executeSpinsForTrigger(game, SpinService.AutoTrigger.STRATEGY);
@@ -834,7 +839,9 @@ public static void sendStatusReminders(Game game, Player player) {
     }
 
     public static void startStatusHomework(GenericInteractionCreateEvent event, Game game) {
+        String previousPhaseOfGame = game.getPhaseOfGame();
         game.setPhaseOfGame("statusHomework");
+        GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "statusHomework");
         game.setStoredValue("startTimeOfRound" + game.getRound() + "StatusHomework", System.currentTimeMillis() + "");
         GMService.logActivity(game, "**StatusHomework** Phase for Round " + game.getRound() + " started.", true);
         // first do cleanup if necessary
@@ -1116,7 +1123,9 @@ public static void postSurveyResults(Game game) {
     public static void startActionPhase(GenericInteractionCreateEvent event, Game game, boolean incrementTgs) {
         boolean isFowPrivateGame = game.isFowMode();
         game.setStoredValue("willRevolution", "");
+        String previousPhaseOfGame = game.getPhaseOfGame();
         game.setPhaseOfGame("action");
+        GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "action");
         GMService.logActivity(game, "**Action** Phase for Round " + game.getRound() + " started.", true);
         for (Player p2 : game.getRealPlayers()) {
             ButtonHelperActionCards.checkForAssigningExtremeDuress(game, p2);
diff --git a/src/main/java/ti4/service/strategycard/PickStrategyCardService.java b/src/main/java/ti4/service/strategycard/PickStrategyCardService.java
index 7e9193a864..c4a6fcdc87 100644
--- a/src/main/java/ti4/service/strategycard/PickStrategyCardService.java
+++ b/src/main/java/ti4/service/strategycard/PickStrategyCardService.java
@@ -17,6 +17,7 @@
 import ti4.message.MessageHelper;
 import ti4.service.game.StartPhaseService;
 import ti4.service.player.PlayerStatsService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 
 @UtilityClass
 public class PickStrategyCardService {
@@ -37,6 +38,7 @@ public static void secondHalfOfSCPick(GenericInteractionCreateEvent event, Playe
         }
 
         boolean nextCorrectPing = false;
+        String previousPhaseOfGame = game.getPhaseOfGame();
         Queue<Player> players = new ArrayDeque<>(activePlayers);
         while (players.iterator().hasNext()) {
             Player currentPlayer = players.poll();
@@ -66,6 +68,7 @@ public static void secondHalfOfSCPick(GenericInteractionCreateEvent event, Playe
                 game.updateActivePlayer(privatePlayer);
                 game.setPhaseOfGame("strategy");
                 game.updateActivePlayer(privatePlayer);
+                GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "strategy");
                 boolean queuedPick = false;
                 if (event instanceof ButtonInteractionEvent bevent) {
                     queuedPick = checkForQueuedSCPick(bevent, privatePlayer, game, msgExtra);
@@ -80,6 +83,7 @@ public static void secondHalfOfSCPick(GenericInteractionCreateEvent event, Playe
             if (!allPicked) {
                 game.updateActivePlayer(privatePlayer);
                 game.setPhaseOfGame("strategy");
+                GameWebhookNotifierFacade.phaseChanged(game, previousPhaseOfGame, "strategy");
                 boolean queuedPick;
                 if (event instanceof ButtonInteractionEvent bevent) {
                     queuedPick = checkForQueuedSCPick(bevent, privatePlayer, game, msgExtra);
diff --git a/src/main/java/ti4/service/turn/StartTurnService.java b/src/main/java/ti4/service/turn/StartTurnService.java
index 936e8a3254..625c894b2f 100644
--- a/src/main/java/ti4/service/turn/StartTurnService.java
+++ b/src/main/java/ti4/service/turn/StartTurnService.java
@@ -53,6 +53,7 @@
 import ti4.service.leader.CommanderUnlockCheckService;
 import ti4.service.strategycard.PlayStrategyCardService;
 import ti4.service.strategycard.StrategyCardMessageService;
+import ti4.service.webhook.GameWebhookNotifierFacade;
 import ti4.settings.users.UserSettingsManager;
 
 @UtilityClass
@@ -152,6 +153,7 @@ public static void turnStart(GenericInteractionCreateEvent event, Game game, Pla
 
         game.updateActivePlayer(player);
         game.setPhaseOfGame("action");
+        GameWebhookNotifierFacade.turnChanged(game);
         ButtonHelperFactionSpecific.resolveMilitarySupportCheck(player, game);
         if (NetrunnersPromissoryHandler.shouldOfferSharedNetworkAccessButtons(player, game)) {
             NetrunnersPromissoryHandler.offerSharedNetworkAccessButtons(player, game);
diff --git a/src/main/java/ti4/service/webhook/GameWebhookEventType.java b/src/main/java/ti4/service/webhook/GameWebhookEventType.java
new file mode 100644
index 0000000000..8b02671bf3
--- /dev/null
+++ b/src/main/java/ti4/service/webhook/GameWebhookEventType.java
@@ -0,0 +1,51 @@
+package ti4.service.webhook;
+
+import java.util.Map;
+
+public enum GameWebhookEventType {
+    TURN_CHANGED(
+            "A new player's turn has started.",
+            "Emitted after the bot updates the active player in StartTurnService.turnStart.",
+            Map.of(
+                    "gameName", "string",
+                    "eventType", "string",
+                    "phaseOfGame", "string",
+                    "round", "integer",
+                    "activePlayerId", "string",
+                    "activeFaction", "string",
+                    "timestamp", "date-time")),
+    PHASE_CHANGED(
+            "The game entered a new core phase.",
+            "Emitted after the bot updates the game phase for strategy, action, status, or agenda.",
+            Map.of(
+                    "gameName", "string",
+                    "eventType", "string",
+                    "previousPhaseOfGame", "string|null",
+                    "phaseOfGame", "string",
+                    "round", "integer",
+                    "activePlayerId", "string|null",
+                    "activeFaction", "string|null",
+                    "timestamp", "date-time"));
+
+    private final String description;
+    private final String trigger;
+    private final Map<String, String> payloadFields;
+
+    GameWebhookEventType(String description, String trigger, Map<String, String> payloadFields) {
+        this.description = description;
+        this.trigger = trigger;
+        this.payloadFields = payloadFields;
+    }
+
+    public String getDescription() {
+        return description;
+    }
+
+    public String getTrigger() {
+        return trigger;
+    }
+
+    public Map<String, String> getPayloadFields() {
+        return payloadFields;
+    }
+}
diff --git a/src/main/java/ti4/service/webhook/GameWebhookNotifier.java b/src/main/java/ti4/service/webhook/GameWebhookNotifier.java
new file mode 100644
index 0000000000..9fa93166af
--- /dev/null
+++ b/src/main/java/ti4/service/webhook/GameWebhookNotifier.java
@@ -0,0 +1,81 @@
+package ti4.service.webhook;
+
+import java.time.Instant;
+import java.util.Locale;
+import org.springframework.stereotype.Service;
+import ti4.game.Game;
+import ti4.game.Player;
+import ti4.spring.service.webhook.GameWebhookSubscriptionService;
+import ti4.spring.service.webhook.WebhookUserEntity;
+
+@Service
+public class GameWebhookNotifier {
+
+    private final GameWebhookSubscriptionService subscriptionService;
+    private final WebhookDispatchService dispatchService;
+
+    public GameWebhookNotifier(GameWebhookSubscriptionService subscriptionService, WebhookDispatchService dispatchService) {
+        this.subscriptionService = subscriptionService;
+        this.dispatchService = dispatchService;
+    }
+
+    public void turnChanged(Game game) {
+        if (game == null) return;
+        String phaseOfGame = normalizePhase(game.getPhaseOfGame());
+        if (phaseOfGame == null) return;
+
+        Player activePlayer = game.getActivePlayer();
+        GameWebhookPayload payload = new GameWebhookPayload(
+                game.getName(),
+                GameWebhookEventType.TURN_CHANGED,
+                null,
+                phaseOfGame,
+                game.getRound(),
+                activePlayer == null ? null : activePlayer.getUserID(),
+                activePlayer == null ? null : activePlayer.getFaction(),
+                Instant.now());
+        dispatchToSubscribers(game.getName(), GameWebhookEventType.TURN_CHANGED, payload);
+    }
+
+    public boolean phaseChanged(Game game, String previousPhaseOfGame) {
+        if (game == null) return false;
+        return phaseChanged(game, previousPhaseOfGame, game.getPhaseOfGame());
+    }
+
+    public boolean phaseChanged(Game game, String previousPhaseOfGame, String phaseOfGame) {
+        if (game == null) return false;
+        String previous = normalizePhase(previousPhaseOfGame);
+        String current = normalizePhase(phaseOfGame);
+        if (current == null || current.equals(previous)) return false;
+
+        GameWebhookPayload payload = new GameWebhookPayload(
+                game.getName(),
+                GameWebhookEventType.PHASE_CHANGED,
+                previous,
+                current,
+                game.getRound(),
+                null,
+                null,
+                Instant.now());
+        dispatchToSubscribers(game.getName(), GameWebhookEventType.PHASE_CHANGED, payload);
+        return true;
+    }
+
+    private void dispatchToSubscribers(String gameName, GameWebhookEventType eventType, GameWebhookPayload payload) {
+        for (WebhookUserEntity subscriber : subscriptionService.getSubscribers(gameName, eventType)) {
+            if (subscriber.isActive()) {
+                dispatchService.dispatch(subscriber.getCallbackUrl(), payload);
+            }
+        }
+    }
+
+    private static String normalizePhase(String phaseOfGame) {
+        if (phaseOfGame == null) return null;
+        String normalized = phaseOfGame.trim().toLowerCase(Locale.ROOT);
+        if (normalized.startsWith("strategy")) return "strategy";
+        if (normalized.startsWith("action")) return "action";
+        if (normalized.startsWith("status")) return "status";
+        if (normalized.startsWith("agenda")) return "agenda";
+        return null;
+    }
+}
diff --git a/src/main/java/ti4/service/webhook/GameWebhookNotifierFacade.java b/src/main/java/ti4/service/webhook/GameWebhookNotifierFacade.java
new file mode 100644
index 0000000000..e1edb4f361
--- /dev/null
+++ b/src/main/java/ti4/service/webhook/GameWebhookNotifierFacade.java
@@ -0,0 +1,41 @@
+package ti4.service.webhook;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+import lombok.experimental.UtilityClass;
+import ti4.game.Game;
+import ti4.logging.BotLogger;
+import ti4.spring.context.SpringContext;
+
+@UtilityClass
+public class GameWebhookNotifierFacade {
+
+    private static final AtomicBoolean LOOKUP_FAILURE_LOGGED = new AtomicBoolean(false);
+
+    public static void turnChanged(Game game) {
+        GameWebhookNotifier notifier = getNotifier();
+        if (notifier != null) {
+            notifier.turnChanged(game);
+        }
+    }
+
+    public static boolean phaseChanged(Game game, String previousPhaseOfGame) {
+        GameWebhookNotifier notifier = getNotifier();
+        return notifier != null && notifier.phaseChanged(game, previousPhaseOfGame);
+    }
+
+    public static boolean phaseChanged(Game game, String previousPhaseOfGame, String phaseOfGame) {
+        GameWebhookNotifier notifier = getNotifier();
+        return notifier != null && notifier.phaseChanged(game, previousPhaseOfGame, phaseOfGame);
+    }
+
+    private static GameWebhookNotifier getNotifier() {
+        try {
+            return SpringContext.getBean(GameWebhookNotifier.class);
+        } catch (Exception e) {
+            if (LOOKUP_FAILURE_LOGGED.compareAndSet(false, true)) {
+                BotLogger.warning("Game webhook notifier is unavailable; webhook notifications will be skipped.", e);
+            }
+            return null;
+        }
+    }
+}
diff --git a/src/main/java/ti4/service/webhook/GameWebhookPayload.java b/src/main/java/ti4/service/webhook/GameWebhookPayload.java
new file mode 100644
index 0000000000..bca89f3956
--- /dev/null
+++ b/src/main/java/ti4/service/webhook/GameWebhookPayload.java
@@ -0,0 +1,15 @@
+package ti4.service.webhook;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import java.time.Instant;
+
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public record GameWebhookPayload(
+        String gameName,
+        GameWebhookEventType eventType,
+        String previousPhaseOfGame,
+        String phaseOfGame,
+        int round,
+        String activePlayerId,
+        String activeFaction,
+        Instant timestamp) {}
diff --git a/src/main/java/ti4/service/webhook/WebhookDispatchService.java b/src/main/java/ti4/service/webhook/WebhookDispatchService.java
new file mode 100644
index 0000000000..8a19f0f3e5
--- /dev/null
+++ b/src/main/java/ti4/service/webhook/WebhookDispatchService.java
@@ -0,0 +1,96 @@
+package ti4.service.webhook;
+
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.time.Duration;
+import org.springframework.stereotype.Service;
+import ti4.executors.ExecutorServiceManager;
+import ti4.json.JsonMapperManager;
+import ti4.logging.BotLogger;
+import ti4.website.EgressClientManager;
+import tools.jackson.databind.json.JsonMapper;
+
+@Service
+public class WebhookDispatchService {
+
+    private static final Duration REQUEST_TIMEOUT = Duration.ofSeconds(5);
+    private static final String CONTENT_TYPE_JSON = "application/json";
+
+    private final JsonMapper jsonMapper;
+    private final HttpClient httpClient;
+
+    public WebhookDispatchService() {
+        this(JsonMapperManager.basic(), EgressClientManager.getHttpClient());
+    }
+
+    WebhookDispatchService(JsonMapper jsonMapper, HttpClient httpClient) {
+        this.jsonMapper = jsonMapper;
+        this.httpClient = httpClient;
+    }
+
+    public void dispatch(String callbackUrl, GameWebhookPayload payload) {
+        ExecutorServiceManager.runAsync("webhook-dispatch", () -> dispatchWithRetry(callbackUrl, payload));
+    }
+
+    private void dispatchWithRetry(String callbackUrl, GameWebhookPayload payload) {
+        boolean retry;
+        try {
+            HttpResponse<String> response = send(callbackUrl, payload);
+            retry = shouldRetry(response.statusCode());
+            if (retry) logStatus(callbackUrl, response.statusCode());
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            BotLogger.warning("Webhook dispatch interrupted for host `" + host(callbackUrl) + "`.");
+            return;
+        } catch (IOException e) {
+            retry = true;
+            BotLogger.warning("Webhook dispatch to host `" + host(callbackUrl) + "` failed with transient exception `"
+                    + e.getClass().getSimpleName() + "`; retrying once.");
+        } catch (Exception e) {
+            BotLogger.warning("Webhook dispatch failed for host `" + host(callbackUrl) + "` with exception `"
+                    + e.getClass().getSimpleName() + "`.");
+            return;
+        }
+
+        if (!retry) return;
+        try {
+            HttpResponse<String> retryResponse = send(callbackUrl, payload);
+            logStatus(callbackUrl, retryResponse.statusCode());
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            BotLogger.warning("Webhook dispatch retry interrupted for host `" + host(callbackUrl) + "`.");
+        } catch (Exception e) {
+            BotLogger.warning("Webhook dispatch retry failed for host `" + host(callbackUrl) + "` with exception `"
+                    + e.getClass().getSimpleName() + "`.");
+        }
+    }
+
+    private HttpResponse<String> send(String callbackUrl, GameWebhookPayload payload) throws Exception {
+        String body = jsonMapper.writeValueAsString(payload);
+        HttpRequest request = HttpRequest.newBuilder(URI.create(callbackUrl))
+                .timeout(REQUEST_TIMEOUT)
+                .header("Content-Type", CONTENT_TYPE_JSON)
+                .POST(HttpRequest.BodyPublishers.ofString(body))
+                .build();
+        return httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+    }
+
+    private static void logStatus(String callbackUrl, int statusCode) {
+        BotLogger.info("Webhook dispatch to host `" + host(callbackUrl) + "` returned HTTP " + statusCode + ".");
+    }
+
+    private static String host(String callbackUrl) {
+        try {
+            return URI.create(callbackUrl).getHost();
+        } catch (Exception e) {
+            return "unknown";
+        }
+    }
+
+    static boolean shouldRetry(int statusCode) {
+        return statusCode == 408 || statusCode == 429 || (statusCode >= 500 && statusCode < 600);
+    }
+}
diff --git a/src/main/java/ti4/spring/api/webhook/GameWebhookApiController.java b/src/main/java/ti4/spring/api/webhook/GameWebhookApiController.java
new file mode 100644
index 0000000000..32698e52eb
--- /dev/null
+++ b/src/main/java/ti4/spring/api/webhook/GameWebhookApiController.java
@@ -0,0 +1,64 @@
+package ti4.spring.api.webhook;
+
+import java.util.Arrays;
+import java.util.List;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import ti4.service.webhook.GameWebhookEventType;
+import ti4.spring.context.SetupRequestContext;
+import ti4.spring.service.webhook.GameWebhookSubscriptionService;
+import ti4.spring.service.webhook.GameWebhookSubscriptionService.SubscribeResult;
+
+@RestController
+@RequestMapping("/api/public/game")
+public class GameWebhookApiController {
+
+    private final GameWebhookSubscriptionService subscriptionService;
+
+    public GameWebhookApiController(GameWebhookSubscriptionService subscriptionService) {
+        this.subscriptionService = subscriptionService;
+    }
+
+    @GetMapping("/webhook/eventTypes")
+    public List<GameWebhookEventTypeResponse> getEventTypes() {
+        return Arrays.stream(GameWebhookEventType.values())
+                .map(GameWebhookEventTypeResponse::from)
+                .toList();
+    }
+
+    @SetupRequestContext(false)
+    @PutMapping("/{gameId}/webhook")
+    public ResponseEntity<Void> put(
+            @PathVariable("gameId") String gameName,
+            @RequestHeader(name = "X-API-Key", required = false) String apiKey,
+            @RequestBody GameWebhookSubscriptionRequest request) {
+        if (apiKey == null || apiKey.isBlank()) return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+        return response(subscriptionService.subscribe(gameName, apiKey, request == null ? null : request.eventTypes()));
+    }
+
+    @SetupRequestContext(false)
+    @DeleteMapping("/{gameId}/webhook")
+    public ResponseEntity<Void> delete(
+            @PathVariable("gameId") String gameName, @RequestHeader(name = "X-API-Key", required = false) String apiKey) {
+        if (apiKey == null || apiKey.isBlank()) return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+        return response(subscriptionService.delete(gameName, apiKey));
+    }
+
+    private static ResponseEntity<Void> response(SubscribeResult result) {
+        return switch (result) {
+            case OK -> ResponseEntity.ok().build();
+            case UNAUTHORIZED -> ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+            case UNKNOWN_GAME -> ResponseEntity.status(HttpStatus.NOT_FOUND).build();
+            case FORBIDDEN_GAME -> ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+            case UNSUPPORTED_EVENT_TYPE -> ResponseEntity.badRequest().build();
+        };
+    }
+}
diff --git a/src/main/java/ti4/spring/api/webhook/GameWebhookEventTypeResponse.java b/src/main/java/ti4/spring/api/webhook/GameWebhookEventTypeResponse.java
new file mode 100644
index 0000000000..09e80684d1
--- /dev/null
+++ b/src/main/java/ti4/spring/api/webhook/GameWebhookEventTypeResponse.java
@@ -0,0 +1,27 @@
+package ti4.spring.api.webhook;
+
+import java.util.Map;
+import ti4.service.webhook.GameWebhookEventType;
+
+public record GameWebhookEventTypeResponse(
+        String name,
+        String description,
+        String trigger,
+        String method,
+        String contentType,
+        int timeoutSeconds,
+        String retries,
+        Map<String, String> payloadFields) {
+
+    public static GameWebhookEventTypeResponse from(GameWebhookEventType eventType) {
+        return new GameWebhookEventTypeResponse(
+                eventType.name(),
+                eventType.getDescription(),
+                eventType.getTrigger(),
+                "POST",
+                "application/json",
+                5,
+                "Transient failures only: timeout, IO error, HTTP 408, 429, or 5xx",
+                eventType.getPayloadFields());
+    }
+}
diff --git a/src/main/java/ti4/spring/api/webhook/GameWebhookSubscriptionRequest.java b/src/main/java/ti4/spring/api/webhook/GameWebhookSubscriptionRequest.java
new file mode 100644
index 0000000000..a5abe35201
--- /dev/null
+++ b/src/main/java/ti4/spring/api/webhook/GameWebhookSubscriptionRequest.java
@@ -0,0 +1,5 @@
+package ti4.spring.api.webhook;
+
+import java.util.List;
+
+public record GameWebhookSubscriptionRequest(List<String> eventTypes) {}
diff --git a/src/main/java/ti4/spring/service/webhook/GameWebhookEntity.java b/src/main/java/ti4/spring/service/webhook/GameWebhookEntity.java
new file mode 100644
index 0000000000..e5471be6c3
--- /dev/null
+++ b/src/main/java/ti4/spring/service/webhook/GameWebhookEntity.java
@@ -0,0 +1,33 @@
+package ti4.spring.service.webhook;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Entity
+@Table(
+        name = "game_webhook",
+        uniqueConstraints = @UniqueConstraint(columnNames = {"game_name", "webhook_user_id"}))
+public class GameWebhookEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(name = "game_name", nullable = false)
+    private String gameName;
+
+    @Column(name = "webhook_user_id", nullable = false)
+    private Long webhookUserId;
+
+    @Column(name = "event_types_csv", nullable = false)
+    private String eventTypesCsv;
+}
diff --git a/src/main/java/ti4/spring/service/webhook/GameWebhookRepository.java b/src/main/java/ti4/spring/service/webhook/GameWebhookRepository.java
new file mode 100644
index 0000000000..d02a80686b
--- /dev/null
+++ b/src/main/java/ti4/spring/service/webhook/GameWebhookRepository.java
@@ -0,0 +1,14 @@
+package ti4.spring.service.webhook;
+
+import java.util.List;
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface GameWebhookRepository extends JpaRepository<GameWebhookEntity, Long> {
+
+    Optional<GameWebhookEntity> findByGameNameAndWebhookUserId(String gameName, Long webhookUserId);
+
+    List<GameWebhookEntity> findByGameName(String gameName);
+
+    void deleteByGameNameAndWebhookUserId(String gameName, Long webhookUserId);
+}
diff --git a/src/main/java/ti4/spring/service/webhook/GameWebhookSubscriptionService.java b/src/main/java/ti4/spring/service/webhook/GameWebhookSubscriptionService.java
new file mode 100644
index 0000000000..f48929d68f
--- /dev/null
+++ b/src/main/java/ti4/spring/service/webhook/GameWebhookSubscriptionService.java
@@ -0,0 +1,122 @@
+package ti4.spring.service.webhook;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+import java.util.Arrays;
+import java.util.HexFormat;
+import java.util.List;
+import java.util.Locale;
+import java.util.Optional;
+import java.util.Set;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import ti4.game.persistence.GameManager;
+import ti4.game.persistence.ManagedGame;
+import ti4.service.webhook.GameWebhookEventType;
+
+@Service
+public class GameWebhookSubscriptionService {
+
+    public enum SubscribeResult {
+        OK,
+        UNAUTHORIZED,
+        UNKNOWN_GAME,
+        FORBIDDEN_GAME,
+        UNSUPPORTED_EVENT_TYPE
+    }
+
+    private final WebhookUserRepository webhookUserRepository;
+    private final GameWebhookRepository gameWebhookRepository;
+
+    public GameWebhookSubscriptionService(
+            WebhookUserRepository webhookUserRepository, GameWebhookRepository gameWebhookRepository) {
+        this.webhookUserRepository = webhookUserRepository;
+        this.gameWebhookRepository = gameWebhookRepository;
+    }
+
+    @Transactional
+    public SubscribeResult subscribe(String gameName, String apiKey, List<String> eventTypes) {
+        WebhookUserEntity user = getActiveUser(apiKey);
+        if (user == null) return SubscribeResult.UNAUTHORIZED;
+        if (!GameManager.isValid(gameName)) return SubscribeResult.UNKNOWN_GAME;
+        if (!canSubscribe(gameName)) return SubscribeResult.FORBIDDEN_GAME;
+        if (!areSupported(eventTypes)) return SubscribeResult.UNSUPPORTED_EVENT_TYPE;
+
+        String eventTypesCsv = normalizedEventTypes(eventTypes).collect(Collectors.joining(","));
+        GameWebhookEntity entity = gameWebhookRepository
+                .findByGameNameAndWebhookUserId(gameName, user.getId())
+                .orElseGet(GameWebhookEntity::new);
+        entity.setGameName(gameName);
+        entity.setWebhookUserId(user.getId());
+        entity.setEventTypesCsv(eventTypesCsv);
+        gameWebhookRepository.save(entity);
+        return SubscribeResult.OK;
+    }
+
+    @Transactional
+    public SubscribeResult delete(String gameName, String apiKey) {
+        WebhookUserEntity user = getActiveUser(apiKey);
+        if (user == null) return SubscribeResult.UNAUTHORIZED;
+        if (!GameManager.isValid(gameName)) return SubscribeResult.UNKNOWN_GAME;
+        if (!canSubscribe(gameName)) return SubscribeResult.FORBIDDEN_GAME;
+        gameWebhookRepository.deleteByGameNameAndWebhookUserId(gameName, user.getId());
+        return SubscribeResult.OK;
+    }
+
+    public List<WebhookUserEntity> getSubscribers(String gameName, GameWebhookEventType eventType) {
+        if (!canSubscribe(gameName)) return List.of();
+        return gameWebhookRepository.findByGameName(gameName).stream()
+                .filter(subscription -> includes(subscription, eventType))
+                .map(subscription -> webhookUserRepository.findById(subscription.getWebhookUserId()))
+                .flatMap(Optional::stream)
+                .filter(WebhookUserEntity::isActive)
+                .toList();
+    }
+
+    private WebhookUserEntity getActiveUser(String apiKey) {
+        if (apiKey == null || apiKey.isBlank()) return null;
+        return webhookUserRepository.findByApiKeyHashAndActiveTrue(sha256(apiKey)).orElse(null);
+    }
+
+    private static boolean canSubscribe(String gameName) {
+        ManagedGame managedGame = GameManager.getManagedGame(gameName);
+        return managedGame != null && !managedGame.isFowMode();
+    }
+
+    private static boolean areSupported(List<String> eventTypes) {
+        if (eventTypes == null || eventTypes.isEmpty()) return false;
+        Set<String> supported = Arrays.stream(GameWebhookEventType.values()).map(Enum::name).collect(Collectors.toSet());
+        return eventTypes.stream()
+                .map(GameWebhookSubscriptionService::normalizeEventType)
+                .allMatch(supported::contains);
+    }
+
+    private static Stream<String> normalizedEventTypes(List<String> eventTypes) {
+        return eventTypes.stream()
+                .map(GameWebhookSubscriptionService::normalizeEventType)
+                .distinct()
+                .sorted();
+    }
+
+    private static String normalizeEventType(String eventType) {
+        return eventType == null ? null : eventType.trim().toUpperCase(Locale.ROOT);
+    }
+
+    private static boolean includes(GameWebhookEntity subscription, GameWebhookEventType eventType) {
+        return Arrays.stream(subscription.getEventTypesCsv().split(","))
+                .map(String::trim)
+                .anyMatch(value -> value.equals(eventType.name()));
+    }
+
+    public static String sha256(String value) {
+        try {
+            MessageDigest digest = MessageDigest.getInstance("SHA-256");
+            return HexFormat.of().formatHex(digest.digest(value.getBytes(StandardCharsets.UTF_8)));
+        } catch (NoSuchAlgorithmException e) {
+            throw new IllegalStateException("SHA-256 is unavailable", e);
+        }
+    }
+}
diff --git a/src/main/java/ti4/spring/service/webhook/WebhookUserEntity.java b/src/main/java/ti4/spring/service/webhook/WebhookUserEntity.java
new file mode 100644
index 0000000000..ffa237acb9
--- /dev/null
+++ b/src/main/java/ti4/spring/service/webhook/WebhookUserEntity.java
@@ -0,0 +1,33 @@
+package ti4.spring.service.webhook;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.Getter;
+import lombok.Setter;
+
+@Getter
+@Setter
+@Entity
+@Table(name = "webhook_user")
+public class WebhookUserEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false)
+    private String description;
+
+    @Column(name = "callback_url", nullable = false, length = 2048)
+    private String callbackUrl;
+
+    @Column(name = "api_key_hash", nullable = false, unique = true)
+    private String apiKeyHash;
+
+    @Column(nullable = false)
+    private boolean active;
+}
diff --git a/src/main/java/ti4/spring/service/webhook/WebhookUserRepository.java b/src/main/java/ti4/spring/service/webhook/WebhookUserRepository.java
new file mode 100644
index 0000000000..dd56b966fc
--- /dev/null
+++ b/src/main/java/ti4/spring/service/webhook/WebhookUserRepository.java
@@ -0,0 +1,9 @@
+package ti4.spring.service.webhook;
+
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface WebhookUserRepository extends JpaRepository<WebhookUserEntity, Long> {
+
+    Optional<WebhookUserEntity> findByApiKeyHashAndActiveTrue(String apiKeyHash);
+}
diff --git a/src/test/java/ti4/service/webhook/GameWebhookNotifierTest.java b/src/test/java/ti4/service/webhook/GameWebhookNotifierTest.java
new file mode 100644
index 0000000000..d029217174
--- /dev/null
+++ b/src/test/java/ti4/service/webhook/GameWebhookNotifierTest.java
@@ -0,0 +1,99 @@
+package ti4.service.webhook;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import ti4.game.Game;
+import ti4.game.Player;
+import ti4.spring.service.webhook.GameWebhookSubscriptionService;
+import ti4.spring.service.webhook.WebhookUserEntity;
+
+class GameWebhookNotifierTest {
+
+    private final GameWebhookSubscriptionService subscriptionService = mock(GameWebhookSubscriptionService.class);
+    private final WebhookDispatchService dispatchService = mock(WebhookDispatchService.class);
+    private final GameWebhookNotifier notifier = new GameWebhookNotifier(subscriptionService, dispatchService);
+
+    @Test
+    void turnChangedDispatchesToActiveSubscribers() {
+        Game game = mock(Game.class);
+        Player activePlayer = mock(Player.class);
+        WebhookUserEntity subscriber = subscriber("https://example.test/webhook", true);
+        when(game.getName()).thenReturn("pbd1234");
+        when(game.getPhaseOfGame()).thenReturn("action");
+        when(game.getRound()).thenReturn(3);
+        when(game.getActivePlayer()).thenReturn(activePlayer);
+        when(activePlayer.getUserID()).thenReturn("123456789");
+        when(activePlayer.getFaction()).thenReturn("arborec");
+        when(subscriptionService.getSubscribers("pbd1234", GameWebhookEventType.TURN_CHANGED))
+                .thenReturn(List.of(subscriber));
+
+        notifier.turnChanged(game);
+
+        ArgumentCaptor<GameWebhookPayload> payload = ArgumentCaptor.forClass(GameWebhookPayload.class);
+        verify(dispatchService).dispatch("https://example.test/webhook", payload.capture());
+        assertEquals("pbd1234", payload.getValue().gameName());
+        assertEquals(GameWebhookEventType.TURN_CHANGED, payload.getValue().eventType());
+        assertEquals("action", payload.getValue().phaseOfGame());
+        assertEquals(3, payload.getValue().round());
+        assertEquals("123456789", payload.getValue().activePlayerId());
+        assertEquals("arborec", payload.getValue().activeFaction());
+        assertNotNull(payload.getValue().timestamp());
+    }
+
+    @Test
+    void phaseChangedIgnoresSameNormalizedPhase() {
+        Game game = mock(Game.class);
+
+        boolean emitted = notifier.phaseChanged(game, "statusHomework", "statusScoring");
+
+        assertFalse(emitted);
+        verifyNoInteractions(subscriptionService, dispatchService);
+    }
+
+    @Test
+    void turnChangedIgnoresUnknownPhase() {
+        Game game = mock(Game.class);
+        when(game.getPhaseOfGame()).thenReturn("miltydraft");
+
+        notifier.turnChanged(game);
+
+        verifyNoInteractions(subscriptionService, dispatchService);
+    }
+
+    @Test
+    void phaseChangedDispatchesPreviousAndCurrentPhase() {
+        Game game = mock(Game.class);
+        WebhookUserEntity subscriber = subscriber("https://example.test/phase", true);
+        when(game.getName()).thenReturn("pbd1234");
+        when(game.getRound()).thenReturn(2);
+        when(subscriptionService.getSubscribers("pbd1234", GameWebhookEventType.PHASE_CHANGED))
+                .thenReturn(List.of(subscriber));
+
+        boolean emitted = notifier.phaseChanged(game, "strategy", "action");
+
+        assertTrue(emitted);
+        ArgumentCaptor<GameWebhookPayload> payload = ArgumentCaptor.forClass(GameWebhookPayload.class);
+        verify(dispatchService).dispatch("https://example.test/phase", payload.capture());
+        assertEquals(GameWebhookEventType.PHASE_CHANGED, payload.getValue().eventType());
+        assertEquals("strategy", payload.getValue().previousPhaseOfGame());
+        assertEquals("action", payload.getValue().phaseOfGame());
+        assertEquals(2, payload.getValue().round());
+    }
+
+    private static WebhookUserEntity subscriber(String callbackUrl, boolean active) {
+        WebhookUserEntity subscriber = new WebhookUserEntity();
+        subscriber.setCallbackUrl(callbackUrl);
+        subscriber.setActive(active);
+        return subscriber;
+    }
+}
diff --git a/src/test/java/ti4/service/webhook/WebhookDispatchServiceTest.java b/src/test/java/ti4/service/webhook/WebhookDispatchServiceTest.java
new file mode 100644
index 0000000000..31d40cdd00
--- /dev/null
+++ b/src/test/java/ti4/service/webhook/WebhookDispatchServiceTest.java
@@ -0,0 +1,27 @@
+package ti4.service.webhook;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+class WebhookDispatchServiceTest {
+
+    @Test
+    void shouldRetryTransientStatuses() {
+        assertTrue(WebhookDispatchService.shouldRetry(408));
+        assertTrue(WebhookDispatchService.shouldRetry(429));
+        assertTrue(WebhookDispatchService.shouldRetry(500));
+        assertTrue(WebhookDispatchService.shouldRetry(502));
+        assertTrue(WebhookDispatchService.shouldRetry(503));
+    }
+
+    @Test
+    void shouldNotRetrySuccessOrNonTransientClientErrors() {
+        assertFalse(WebhookDispatchService.shouldRetry(200));
+        assertFalse(WebhookDispatchService.shouldRetry(201));
+        assertFalse(WebhookDispatchService.shouldRetry(400));
+        assertFalse(WebhookDispatchService.shouldRetry(401));
+        assertFalse(WebhookDispatchService.shouldRetry(404));
+    }
+}
diff --git a/src/test/java/ti4/spring/api/webhook/GameWebhookApiControllerTest.java b/src/test/java/ti4/spring/api/webhook/GameWebhookApiControllerTest.java
new file mode 100644
index 0000000000..a0760782e7
--- /dev/null
+++ b/src/test/java/ti4/spring/api/webhook/GameWebhookApiControllerTest.java
@@ -0,0 +1,477 @@
+package ti4.spring.api.webhook;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.lang.reflect.Method;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Optional;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.MockedStatic;
+import org.mockito.Mockito;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import ti4.game.persistence.GameManager;
+import ti4.game.persistence.ManagedGame;
+import ti4.service.webhook.GameWebhookEventType;
+import ti4.spring.context.SetupRequestContext;
+import ti4.spring.service.webhook.GameWebhookEntity;
+import ti4.spring.service.webhook.GameWebhookRepository;
+import ti4.spring.service.webhook.GameWebhookSubscriptionService;
+import ti4.spring.service.webhook.GameWebhookSubscriptionService.SubscribeResult;
+import ti4.spring.service.webhook.WebhookUserEntity;
+import ti4.spring.service.webhook.WebhookUserRepository;
+
+class GameWebhookApiControllerTest {
+
+    @Test
+    void eventTypesReturnsCompactMetadata() {
+        GameWebhookApiController controller = new GameWebhookApiController(mock(GameWebhookSubscriptionService.class));
+
+        var response = controller.getEventTypes();
+
+        assertEquals(2, response.size());
+        assertEquals("TURN_CHANGED", response.getFirst().name());
+        assertEquals("A new player's turn has started.", response.getFirst().description());
+        assertEquals(
+                "Emitted after the bot updates the active player in StartTurnService.turnStart.",
+                response.getFirst().trigger());
+        assertEquals("POST", response.getFirst().method());
+        assertEquals("application/json", response.getFirst().contentType());
+        assertEquals(5, response.getFirst().timeoutSeconds());
+        assertEquals(
+                "Transient failures only: timeout, IO error, HTTP 408, 429, or 5xx",
+                response.getFirst().retries());
+        assertEquals("string", response.getFirst().payloadFields().get("gameName"));
+        assertEquals("PHASE_CHANGED", response.get(1).name());
+        assertEquals("string|null", response.get(1).payloadFields().get("previousPhaseOfGame"));
+    }
+
+    @Test
+    void mutatingEndpointsUseGameIdPathVariableAndSkipRequestContext() throws NoSuchMethodException {
+        Method put = GameWebhookApiController.class.getMethod(
+                "put", String.class, String.class, GameWebhookSubscriptionRequest.class);
+        Method delete = GameWebhookApiController.class.getMethod("delete", String.class, String.class);
+
+        assertEquals("/{gameId}/webhook", put.getAnnotation(PutMapping.class).value()[0]);
+        assertEquals("/{gameId}/webhook", delete.getAnnotation(DeleteMapping.class).value()[0]);
+        assertEquals(false, put.getAnnotation(SetupRequestContext.class).value());
+        assertEquals(false, delete.getAnnotation(SetupRequestContext.class).value());
+    }
+
+    @Test
+    void putRejectsMissingApiKey() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.put("pbd1234", null, new GameWebhookSubscriptionRequest(List.of("TURN_CHANGED")));
+
+        assertEquals(HttpStatus.UNAUTHORIZED, response.getStatusCode());
+        verify(service, never()).subscribe(any(), any(), any());
+    }
+
+    @Test
+    void putMapsUnknownGameToNotFound() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.subscribe("pbd9999", "key", List.of("TURN_CHANGED"))).thenReturn(SubscribeResult.UNKNOWN_GAME);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.put("pbd9999", "key", new GameWebhookSubscriptionRequest(List.of("TURN_CHANGED")));
+
+        assertEquals(HttpStatus.NOT_FOUND, response.getStatusCode());
+    }
+
+    @Test
+    void putMapsServiceUnauthorizedToUnauthorized() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.subscribe("pbd1234", "key", List.of("TURN_CHANGED"))).thenReturn(SubscribeResult.UNAUTHORIZED);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.put("pbd1234", "key", new GameWebhookSubscriptionRequest(List.of("TURN_CHANGED")));
+
+        assertEquals(HttpStatus.UNAUTHORIZED, response.getStatusCode());
+    }
+
+    @Test
+    void putMapsUnsupportedEventTypeToBadRequest() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.subscribe("pbd1234", "key", List.of("AGENDA_CHANGED")))
+                .thenReturn(SubscribeResult.UNSUPPORTED_EVENT_TYPE);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.put("pbd1234", "key", new GameWebhookSubscriptionRequest(List.of("AGENDA_CHANGED")));
+
+        assertEquals(HttpStatus.BAD_REQUEST, response.getStatusCode());
+    }
+
+    @Test
+    void putMapsForbiddenGameToForbidden() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.subscribe("pbd1234", "key", List.of("TURN_CHANGED"))).thenReturn(SubscribeResult.FORBIDDEN_GAME);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.put("pbd1234", "key", new GameWebhookSubscriptionRequest(List.of("TURN_CHANGED")));
+
+        assertEquals(HttpStatus.FORBIDDEN, response.getStatusCode());
+    }
+
+    @Test
+    void putMapsSuccessfulSubscriptionToOk() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.subscribe("pbd1234", "key", List.of("TURN_CHANGED"))).thenReturn(SubscribeResult.OK);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.put("pbd1234", "key", new GameWebhookSubscriptionRequest(List.of("TURN_CHANGED")));
+
+        assertEquals(HttpStatus.OK, response.getStatusCode());
+    }
+
+    @Test
+    void deleteRejectsMissingApiKey() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.delete("pbd1234", "");
+
+        assertEquals(HttpStatus.UNAUTHORIZED, response.getStatusCode());
+        verify(service, never()).delete(any(), any());
+    }
+
+    @Test
+    void deleteMapsSuccessfulDeletionToOk() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.delete("pbd1234", "key")).thenReturn(SubscribeResult.OK);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.delete("pbd1234", "key");
+
+        assertEquals(HttpStatus.OK, response.getStatusCode());
+    }
+
+    @Test
+    void deleteMapsUnknownGameToNotFound() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.delete("pbd9999", "key")).thenReturn(SubscribeResult.UNKNOWN_GAME);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.delete("pbd9999", "key");
+
+        assertEquals(HttpStatus.NOT_FOUND, response.getStatusCode());
+    }
+
+    @Test
+    void deleteMapsForbiddenGameToForbidden() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.delete("pbd1234", "key")).thenReturn(SubscribeResult.FORBIDDEN_GAME);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.delete("pbd1234", "key");
+
+        assertEquals(HttpStatus.FORBIDDEN, response.getStatusCode());
+    }
+
+    @Test
+    void deleteMapsServiceUnauthorizedToUnauthorized() {
+        GameWebhookSubscriptionService service = mock(GameWebhookSubscriptionService.class);
+        when(service.delete("pbd1234", "key")).thenReturn(SubscribeResult.UNAUTHORIZED);
+        GameWebhookApiController controller = new GameWebhookApiController(service);
+
+        var response = controller.delete("pbd1234", "key");
+
+        assertEquals(HttpStatus.UNAUTHORIZED, response.getStatusCode());
+    }
+
+    @Test
+    void subscribeHashesApiKeyAndSavesSortedDistinctUppercaseEventTypes() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        when(webhookRepository.findByGameNameAndWebhookUserId("pbd1234", 7L)).thenReturn(Optional.empty());
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd1234")).thenReturn(true);
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(publicGame());
+            result = service.subscribe("pbd1234", apiKey, List.of("phase_changed", "TURN_CHANGED", "turn_changed"));
+        }
+
+        ArgumentCaptor<GameWebhookEntity> captor = ArgumentCaptor.forClass(GameWebhookEntity.class);
+        verify(webhookRepository).save(captor.capture());
+        assertEquals(SubscribeResult.OK, result);
+        assertEquals("pbd1234", captor.getValue().getGameName());
+        assertEquals(7L, captor.getValue().getWebhookUserId());
+        assertEquals("PHASE_CHANGED,TURN_CHANGED", captor.getValue().getEventTypesCsv());
+    }
+
+    @Test
+    void subscribeRejectsUnsupportedEventTypeWithoutSaving() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd1234")).thenReturn(true);
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(publicGame());
+            result = service.subscribe("pbd1234", apiKey, List.of("TURN_CHANGED", "AGENDA_CHANGED"));
+        }
+
+        assertEquals(SubscribeResult.UNSUPPORTED_EVENT_TYPE, result);
+        verify(webhookRepository, never()).save(any());
+    }
+
+    @Test
+    void subscribeTreatsNullEventTypeAsUnsupportedWithoutSaving() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd1234")).thenReturn(true);
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(publicGame());
+            result = service.subscribe("pbd1234", apiKey, Arrays.asList("TURN_CHANGED", null));
+        }
+
+        assertEquals(SubscribeResult.UNSUPPORTED_EVENT_TYPE, result);
+        verify(webhookRepository, never()).save(any());
+    }
+
+    @Test
+    void subscribeRejectsInvalidApiKeyWithoutSaving() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        String apiKey = "invalid-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.empty());
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result = service.subscribe("pbd1234", apiKey, List.of("TURN_CHANGED"));
+
+        assertEquals(SubscribeResult.UNAUTHORIZED, result);
+        verify(webhookRepository, never()).save(any());
+    }
+
+    @Test
+    void subscribeRejectsUnknownGameWithoutSaving() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd9999")).thenReturn(false);
+            result = service.subscribe("pbd9999", apiKey, List.of("TURN_CHANGED"));
+        }
+
+        assertEquals(SubscribeResult.UNKNOWN_GAME, result);
+        verify(webhookRepository, never()).save(any());
+    }
+
+    @Test
+    void subscribeRejectsFowGameWithoutSaving() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd1234")).thenReturn(true);
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(fowGame());
+            result = service.subscribe("pbd1234", apiKey, List.of("TURN_CHANGED"));
+        }
+
+        assertEquals(SubscribeResult.FORBIDDEN_GAME, result);
+        verify(webhookRepository, never()).save(any());
+    }
+
+    @Test
+    void subscribeRejectsMissingManagedGameWithoutSaving() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd1234")).thenReturn(true);
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(null);
+            result = service.subscribe("pbd1234", apiKey, List.of("TURN_CHANGED"));
+        }
+
+        assertEquals(SubscribeResult.FORBIDDEN_GAME, result);
+        verify(webhookRepository, never()).save(any());
+    }
+
+    @Test
+    void deleteHashesApiKeyAndDeletesSubscription() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd1234")).thenReturn(true);
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(publicGame());
+            result = service.delete("pbd1234", apiKey);
+        }
+
+        assertEquals(SubscribeResult.OK, result);
+        verify(webhookRepository).deleteByGameNameAndWebhookUserId("pbd1234", 7L);
+    }
+
+    @Test
+    void deleteRejectsInvalidApiKeyWithoutDeleting() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        String apiKey = "invalid-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.empty());
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result = service.delete("pbd1234", apiKey);
+
+        assertEquals(SubscribeResult.UNAUTHORIZED, result);
+        verify(webhookRepository, never()).deleteByGameNameAndWebhookUserId(any(), any());
+    }
+
+    @Test
+    void deleteRejectsUnknownGameWithoutDeleting() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd9999")).thenReturn(false);
+            result = service.delete("pbd9999", apiKey);
+        }
+
+        assertEquals(SubscribeResult.UNKNOWN_GAME, result);
+        verify(webhookRepository, never()).deleteByGameNameAndWebhookUserId(any(), any());
+    }
+
+    @Test
+    void deleteRejectsFowGameWithoutDeleting() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd1234")).thenReturn(true);
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(fowGame());
+            result = service.delete("pbd1234", apiKey);
+        }
+
+        assertEquals(SubscribeResult.FORBIDDEN_GAME, result);
+        verify(webhookRepository, never()).deleteByGameNameAndWebhookUserId(any(), any());
+    }
+
+    @Test
+    void deleteRejectsMissingManagedGameWithoutDeleting() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        WebhookUserEntity user = new WebhookUserEntity();
+        user.setId(7L);
+        String apiKey = "secret-key";
+        when(userRepository.findByApiKeyHashAndActiveTrue(GameWebhookSubscriptionService.sha256(apiKey)))
+                .thenReturn(Optional.of(user));
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        SubscribeResult result;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.isValid("pbd1234")).thenReturn(true);
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(null);
+            result = service.delete("pbd1234", apiKey);
+        }
+
+        assertEquals(SubscribeResult.FORBIDDEN_GAME, result);
+        verify(webhookRepository, never()).deleteByGameNameAndWebhookUserId(any(), any());
+    }
+
+    @Test
+    void getSubscribersReturnsEmptyForFowGameWithoutReadingSubscriptions() {
+        WebhookUserRepository userRepository = mock(WebhookUserRepository.class);
+        GameWebhookRepository webhookRepository = mock(GameWebhookRepository.class);
+        GameWebhookSubscriptionService service = new GameWebhookSubscriptionService(userRepository, webhookRepository);
+
+        List<WebhookUserEntity> subscribers;
+        try (MockedStatic<GameManager> gameManager = Mockito.mockStatic(GameManager.class)) {
+            gameManager.when(() -> GameManager.getManagedGame("pbd1234")).thenReturn(fowGame());
+            subscribers = service.getSubscribers("pbd1234", GameWebhookEventType.TURN_CHANGED);
+        }
+
+        assertTrue(subscribers.isEmpty());
+        verify(webhookRepository, never()).findByGameName(any());
+    }
+
+    @Test
+    void sha256ReturnsLowercaseHexDigest() {
+        assertTrue(GameWebhookSubscriptionService.sha256("secret-key").matches("[0-9a-f]{64}"));
+    }
+
+    private static ManagedGame publicGame() {
+        ManagedGame managedGame = mock(ManagedGame.class);
+        when(managedGame.isFowMode()).thenReturn(false);
+        return managedGame;
+    }
+
+    private static ManagedGame fowGame() {
+        ManagedGame managedGame = mock(ManagedGame.class);
+        when(managedGame.isFowMode()).thenReturn(true);
+        return managedGame;
+    }
+}