HookRaft

A NeoForge mod that bridges your Minecraft server with external webhooks. Forward chat messages to external services and receive messages back into your server. For example, integrate with n8n to get an in-minecraft chat bot for helping players!

Features

• Outbound Webhooks - Forward player chat messages to external HTTP endpoints
• Inbound Webhooks - Receive messages from external services and broadcast them in-game
• Remote Command Execution - Execute Minecraft commands via webhook with whitelist/blacklist security
• Flexible Filtering - Filter which messages are forwarded (all, regex pattern, or command-only)
• In-Game Commands - Send messages directly via /hook command
• Live Configuration - Change settings in-game without restarting
• Fully Async - Non-blocking HTTP requests ensure no server lag

Requirements

• Minecraft 1.21.10
• NeoForge 21.10+
• Java 21+

Installation

1. Download the latest release from the releases page
2. Place the JAR file in your server's mods folder
3. Start the server to generate the config file
4. Configure config/hookraft-server.toml with your webhook URL

Configuration

The configuration file is located at config/hookraft-server.toml:

[webhook]
# URL to send outgoing messages to
outgoingWebhookUrl = "http://your-server.com/api/webhook"
# Port for receiving incoming webhooks
incomingPort = 8000

[chat]
# Filter mode: ALL, REGEX, or COMMAND_ONLY
filterMode = "ALL"
# Regex pattern (when filterMode = REGEX)
regexPattern = "^HookRaft.*"
# Display name for incoming messages
senderName = "HookRaft"
# Display mode: HIGHLIGHTED or DEFAULT
displayMode = "HIGHLIGHTED"

[commands]
# Command filter mode: WHITELIST, BLACKLIST, or DISABLED
commandFilterMode = "WHITELIST"
# Commands allowed when mode is WHITELIST (without leading slash)
allowedCommands = ["give", "tp", "teleport", "time", "weather", "gamemode", "effect", "enchant", "clear", "xp", "experience", "title", "playsound", "particle", "summon", "fill", "setblock"]
# Commands blocked when mode is BLACKLIST (without leading slash)
blockedCommands = ["stop", "op", "deop", "kick", "ban", "ban-ip", "pardon", "whitelist", "save-all", "save-on", "save-off", "execute", "function", "reload"]

[advanced]
# HTTP timeout in milliseconds
connectionTimeout = 10000
# Enable verbose logging
debugLogging = false

Command Filter Modes

Mode	Description
WHITELIST	Only commands in allowedCommands can be executed (recommended)
BLACKLIST	All commands except those in blockedCommands can be executed
DISABLED	Command execution via webhook is completely disabled

Security Note: WHITELIST mode is strongly recommended for production. Only include commands that are safe if misused or accidentally triggered.

Filter Modes

Mode	Description
ALL	Forward all chat messages
REGEX	Only forward messages matching the regex pattern
COMMAND_ONLY	Don't forward chat; only use /hook command

Commands

Command	Description	Permission
/hook <message>	Send a message to the webhook	Everyone
/hookraft send <message>	Same as /hook	Everyone
/hookraft status	Show HookRaft status	Everyone
/hookraft list	List all settings	Everyone
/hookraft get <setting>	Get a setting value	Everyone
/hookraft set <setting> <value>	Change a setting	OP Level 2

API Endpoints

HookRaft exposes the following HTTP endpoints:

POST /api/command

Execute Minecraft commands remotely with whitelist/blacklist security.

Request Body:

{
  "command": "time set day"
}

Accepts command or cmd fields. Commands can be specified with or without the leading slash.

Success Response (200):

{
  "success": true,
  "command": "time set day",
  "result": 1
}

Error Response (403 - Blocked):

{
  "error": "Command 'stop' is not allowed. Check your allowedCommands configuration."
}

Error Response (400 - Invalid):

{
  "success": false,
  "command": "invalid command",
  "error": "Unknown or incomplete command"
}

Security Features:

• Commands are filtered through whitelist/blacklist before execution
• All commands are executed with admin permissions (level 4)
• Command execution can be completely disabled via configuration
• All attempts are logged for auditing

POST /api/receive

Receive messages from external services to broadcast in-game.

Request Body:

{
  "message": "Hello from external service!"
}

Accepts message, text, or content fields.

Response:

{
  "success": true,
  "message": "Message broadcast to server"
}

GET /api/health

Health check endpoint.

Response:

{
  "status": "healthy",
  "mod": "HookRaft",
  "version": "1.0.0",
  "players": 5
}

Outgoing Webhook Format

When HookRaft forwards messages, it sends a POST request with this JSON payload:

Chat Message:

{
  "type": "chat",
  "player": "PlayerName",
  "message": "Hello world!",
  "timestamp": 109971141181051
}

Command Message (via /hook):

{
  "type": "command",
  "sender": "PlayerName",
  "message": "Hello world!",
  "timestamp": 109971141181051
}

Building from Source

# Clone the repository
git clone https://github.com/your-username/hookraft.git
cd hookraft

# Build the mod
./gradlew build

# The JAR will be in build/libs/