Welcome to the official documentation for Valheim Reporter. This mod provides a secure, robust, and customizable in-game reporting system for Valheim servers.
Valheim does not feature a native reporting system of any kind... until now. Valheim Reporter is a simple and convenient solution for servers, ranging from massive communities to small private groups. It is easy to configure and even easier to use.
Valheim Reporter features two basic operational modes. These modes differ in terms of both Mod configuration and how sensitive data is handled. Beyond those differences, the core functionality of the Mod remains the same for both operational modes.
Ideal for small servers played with trusted friends where complexity isn't a priority. Sensitive information is not encrypted and is shared among all players. No personal API is required—simply share the Categories file and go. Read more in Category Configuration File.
Designed for large servers with hundreds of players or those seeking maximum security. All sensitive data is encrypted, and the client never has direct access to server information. Requests are sent to an API that filters and decrypts data before calling the Discord Webhook API, preventing malicious activity. Read more in Category Configuration File.
Valheim Reporter is a stand-alone mod, meaning it does not depend on any extra libraries except for BepInEx. It is 100% Client-Side, which implies that it does not increase the host's workload. Its reporting system is based on Discord WebHook technology (I do not rule out expanding this functionality in the future).
When a player wishes to file an in-game report, they press the button to open the reporting menu (F10 by default), select the option to generate a report, and then choose the category and subcategories (previously configured by the Admin as described in the Category Configuration File). The mod then ensures the user fills in all required information and generates a report that is automatically sent to the specified WebHook.
The main idea behind the mod is to provide a Quality of Life (QoL) improvement for the player. It allows reports requiring screenshots and details to be made as organically as possible within the game, ensuring players can react to in-game dangers in time.
IMPORTANT: A report that has been started will not close until it has been Submitted, so there is no need to worry about losing data if the mod window is closed accidentally.
Data is preserved until the transmission is complete. Additionally, the report is logged locally on the computer at BepInEx/Config/ValheimReporter/Logs. These logs can be set to delete automatically. For more information, please refer to the Configuring Mod CFG section.
BepInEx/plugins folder.categories_sample.json model to create your own.
categories.json file and paste it into ModFolder/ValheimReporter/Data.
Once you have ensured that you followed the steps mentioned in the Category Configuration File (if you are an Admin), or once you have copied the categories.json file as indicated in that section (whether you are a Player or an Admin), follow these steps:
categories.json file.categories.json file.
The mod generates a standard BepInEx configuration file located at BepInEx/config/n1h1lius.valheimreporter.cfg. Below are the available settings to customize your experience.
Open Key
KEYCODE
The key used to toggle the reporting menu. Default: F10.
Fade Duration
FLOAT
The duration of the fade animation when opening/closing the manager. Default: 0.09.
Requirements Remark
BOOLEAN
Enables visual hints in the UI to let you know if a required field is still missing. Default: true.
Confirmation Sound
BOOLEAN
Plays a confirmation sound effect when a report is successfully sent. Default: true.
Discord ID
STRING
Your personal Discord ID. This helps admins identify you in reports. Default: Discord ID.
API Key
STRING
The Server's API URL (Cloudflare Worker) where reports are forwarded. Default: API_KEY.
World Name
STRING
The name of the world or server you are playing on. Default: WORLD_NAME.
Delete Reports
BOOLEAN
Automatically deletes old local logs once the maximum limit is reached. Default: false.
Max Logs
INT32
Maximum amount of local report files to keep. Default: 10.
Output Mode
BOOLEAN
Enables outputting logs to a separate .log file. Default: false.
Map Zoom
FLOAT
Adjusts map screenshot zoom (0.1 close - 1.0 wide). Default: 0.5.
Image Format
ENUM
The format for local screenshots (JPG or PNG). Reports always use high-compression JPG. Default: JPG.
Debug Mode: Enables verbose logging in the BepInEx console for troubleshooting. For developers only. Default: false.
To keep your Discord server safe, you should never put raw Webhook URLs in your configuration files. Use our Category Generator & Encryptor to turn your URLs into secure, encrypted strings.
IMPORTANT: For this step, you will need two things:
{DLL_PATH}\ValheimReporter\Data
Whether you use the Simple Method or the Advanced Method, you must generate a categories.json file and place it in the appropriate path so the Mod can adjust its fields to your server structure.
Remember that the Advanced Method is designed for large servers and/or servers where privacy is a high priority.
Fill in the data according to your Valheim server's reporting structure as you have it organized on Discord, following the steps described below. Finally, download the file and provide it to all your players so they can install it in the proper path.
To reduce the workload on the host server and keep the mod 100% client-side without sacrificing security and privacy, the approach is as follows: The Admin generates the categories.json file as indicated below and distributes it just like in the Simple Method.
Internally, the Category Generator encrypts the WebHook URLs with an encryption key. The Category Generator encrypts the WebHook URLs with an encryption key, making the JSON file held by the players completely encrypted and unreadable. When the mod detects that the WebHooks are encrypted, it automatically routes the request to the API. The API receives the request from the mod, decrypts the URL on the backend, and executes the final call to Discord.
In this way, all traffic is managed outside of the server and the client's computer (to a lesser extent), ensuring a private connection where the client has no way of seeing the final WebHook address, preventing potential abuse and exploits.
SECURITY NOTE: Remember that you must NEVER share your password with anyone. Also, keep in mind that if you share an unencrypted categories.json file, you risk having to eventually delete channels or even the entire server if you provide the file to untrustworthy people. Do so at your own risk.
If you wish to use the Advanced Method, you must enable the "Advanced Mode" toggle. This will display an input modal to enter your encryption password. It is crucial that the password you use is THE SAME password here as it is in the index.js file.
Create categories and subcategories. Enter their names and the Discord channel Webhook, then check the toggles for everything you want to set as a mandatory requirement for the mod to validate and send the report. If you chose Advanced Method, the Webhook URLs will be encrypted automatically.
Once you are finished, click Download JSON. You will receive a file named categories.json. If you look inside, you'll see your Webhooks start with [NH]-3247..., meaning they are now safely encrypted, in case you chose Advanced Method. Otherwise, you will see the regular WebHook URL.
Place your new categories.json file inside the mod folder at: BepInEx/plugins/ValheimReporter/Data/
Pro Tip: You can update this file at any time without restarting the server to change where reports are sent.
The categories.json file is a JSON object that contains the categories and their specific requirements. Once it is correctly configured (or alternatively, if you generate it using my tool, once you have downloaded it), make sure to copy it exactly into the path BepInEx/Config/ValheimReporter/Data. To ensure you are in the correct folder, you should see a file named samples_categories.json, which contains a reference JSON skeleton in case you wish to build your own file by hand.
IMPORTANT: Regardless of whether you use the Simple or Advanced Method, you must generate a categories.json file and share it with all server members. Note that all data in this file will be visible to players; therefore, we strongly recommend using the Advanced Method to encrypt sensitive data and keep your webhooks secure.
The JSON data structure is as follows and must be strictly followed:
{
"category_1": {
"name": "Category 1",
"webhook": "webhook_url",
"required": {
"pictures": true,
"subject": true,
"description": true
},
"subcategories": {
"subcat_1": {
"name": "Subcategory 1",
"webhook": "webhook_url",
"required": {
"pictures": true,
"subject": true,
"description": true
}
}
}
}
}
"name": The display name of the category within the mod's UI."webhook": The Discord channel webhook URL (encrypted if using the Advanced Method)."required": A boolean list indicating the minimum requirements for the report (e.g., set pictures to true to force players to attach screenshots).While you can manually edit this file, I strongly recommend using my Category Generator tool to ensure the formatting is correct and to simplify the encryption process.
SECURITY NOTE: If you use the Advanced Method (manually or via the tool), the encryption password MUST BE IDENTICAL to the one configured in your Decryption API. Otherwise, the system will be unable to process the reports.
The Backend API acts as a secure bridge between your Valheim server and Discord. It encrypts your Webhooks so they are never exposed in the game files. Follow these steps to deploy your own.
In the following lines, I present a simple tutorial on how to set up the API in a private, secure, and free manner using Cloudflare Workers. Their rate limits are quite generous and should be sufficient for a server of 100 to 200 people.
Please note that using Cloudflare as a host is not mandatory. It can be hosted on any platform, including dedicated servers. You simply need to execute the index.js file and configure the .cfg accordingly so that the Mod can point to the correct endpoint.
Go to cloudflare.com and create a free account. You don't need a domain name to use Workers.
In the sidebar, go to Build > Compute > Workers & Pages > Create Application > Start with Hello World. Give the Worker a name and then press Deploy.
Click on Edit Code. Delete everything inside worker.js (or index.js) and paste the code provided in my GitHub repository.
Locate the variable INTERNAL_SECRET_KEY at the top of the script and change "12345" to your own password. Keep it safe!
Important: This password must match the one you use in the Category Generator to encrypt your webhooks.
Click Deploy. Once published, copy the provided URL (e.g., https://valheim-reporter.odinn.workers.dev/).
Paste the Worker URL into your mod configuration file under [ServerRequirements] in the API Key field.
[EXAMPLE] API Key = https://valheim-reporter.odinn.workers.dev/
Valheim Reporter is currently considered a complete project. This means the mod is provided "as is"—what you see in the current version is the intended final experience.
At this time, there are no active plans for major feature updates. My primary focus will be maintenance: ensuring the mod remains compatible with Valheim's official updates and bug-fixes. While it is unlikely that game updates will break the core system, I will provide support to fix any critical issues caused by future game patches.
However, this doesn't mean the door is closed forever. I am always open to suggestions from the community. If during its use I identify significant ways to enhance the workflow, optimize performance, or add powerful new capabilities, I may consider releasing updates to improve the experience for everyone.
Have a great idea or found a bug? Feel free to reach out through the official channels!
Discord User ID (The Number):
1. Open Discord Settings > Advanced.
2. Enable Developer Mode.
3. Right-click your profile picture in any server or DM and select Copy User ID.
Steam ID (SteamID64):
1. Open Steam and go to your Profile.
2. Right-click anywhere and select Copy Page URL.
3. Use a tool like steamid.io to paste that URL and get your SteamID64 (a long number starting with 765...).
Ensure your Cloudflare Worker is updated to the latest version that supports multipart/form-data. If you are using the old version that only sends JSON, images will be ignored by the backend.
This usually means your Encryption Key in the CategoryGenerator.html does not match the INTERNAL_SECRET_KEY in your Cloudflare Worker. If they don't match, the Worker cannot "read" the encrypted webhook.
Yes. If you paste a raw Discord Webhook URL in your categories.json instead of an encrypted string, the mod will send it directly to Discord. However, this is not recommended as anyone could steal your webhook from the game files.
No. The mod uses asynchronous Coroutines to send data. This means the game won't "freeze" or "lag" while the report and images are being uploaded to the backend.
Absolutely! The project is open-source. If you want to help, head over to the GitHub repository, fork the project, and submit a Pull Request with your improvements or new features. I'll be happy to review them!
If you encounter any issues or weird behavior, please report it through the GitHub Issues section. Make sure to include as much detail as possible (logs, screenshots, and steps to reproduce) so I can fix it faster.
Maintaining and developing mods takes time and passion. If you find Valheim Reporter useful for your community and would like to support my work, any donation is greatly appreciated!
Support on Ko-fiThank you for being part of this journey!