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
• 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"

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

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/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/