If your SaaS product’s backend is built with Java—or a JVM-compatible language such as Kotlin, Groovy, Scala, or Clojure—and you want to incorporate WorkOS’ Admin Portal functionality, you can do a dry-run of the Admin Portal integration using our example Java app. It makes use of the WorkOS Kotlin SDK.
If you get stuck while following the steps below and aren't able to resolve the issue by reading our API reference or Admin Portal Setup Guide, please reach out to us at support@workos.com so we can help!
A free WorkOS account, and each of these installed on your machine:
- Java version 1.8+
- The Java Development Kit (JDK), which includes the Java Runtime Environment (JRE)
- In your CLI, navigate to the directory into which you want to clone the Java example app git repo:
$ cd ~/Desktop- Clone the main Java example app repo:
# HTTPS
$ git clone https://github.com/workos/java-example-applications.git
or
# SSH
$ git clone git@github.com:workos/java-example-applications.git- Navigate to the cloned repo:
$ cd java-example-applications/- Obtain and make note of your WorkOS API key and WorkOS Client ID from the WorkOS Dashboard. The locations of these values are shown in the screenshots below.
- Create a .env file in the java-example-applications/ directory to store the environment variables:
$ touch .env- Open the new .env file with your preferred text editor and replace the placeholder values for WORKOS_API_KEY and WORKOS_CLIENT_ID:
WORKOS_API_KEY=your_api_key_here
WORKOS_CLIENT_ID=your_project_id_hereThe .env file is listed in this repo's .gitignore file, so your sensitive information will not be checked into version control. This is an important consideration for keeping sensitive information such as API keys private. The WorkOS Kotlin SDK will read your API key and Client ID from the .env file.
Ngrok is a tool that allows you to map a local endpoint (like localhost) to a public endpoint (like https://something.ngrok.io).
The cloned example app will run on http://localhost:7001. Ngrok will create a tunnel to the application so we can receive webhooks from WorkOS.
- Start a new ngrok session by running this command from the java-example-applications/ directory:
$ ngrok http 7001You’ll see output in the command line from ngrok. You’ll need to keep this CLI window open to persist the ngrok process. The two lines beginning with “Forwarding” in the output are important. The endpoints shown on those two lines with the random alphanumeric strings are the ngrok endpoints, and you’ll also see the localhost endpoints where your web server is running. Note that the only difference between the two “Forwarding” URLs is that one uses HTTP and the other uses HTTPS. For our example, you’ll need to use the HTTPS version which will be in the format of https://.ngrok.io.
You’ll need to keep the CLI tab that’s running ngrok open while you go through the rest of the tutorial. Open a new CLI tab for any other commands you need to run.
- Log into the WorkOS Dashboard and navigate to the Webhooks section:
- Click on the “Create Webhook” button shown in the screenshot above. A Modal will appear. Copy and paste the HTTPS endpoint shown in the ngrok output into the URL field shown in the modal, then append /webhooks to the end of ngrok endpoint. Select all the checkboxes for the purposes of this example, as shown in the screenshot below:
The cloned application is listening for webhook requests at http://localhost:7001/webhooks
- In order for the SDK to validate the WorkOS webhook, we’ll need to supply the webhook’s secret key. To find the secret key, first navigate to the new webhook’s detail page:
- Then locate and copy the secret key:
- Open the .env file in your text editor again, and add this key-value pair beneath the WorkOS API key that’s already there:
WORKOS_WEBHOOK_SECRET=your_webhook_secret- While keeping the ngrok process running in one CLI tab, open another CLI tab and start the server by running this command in the new tab:
$ ./gradlew :java-webhooks-example:run-
Navigate to http://localhost:7001. You’ll see a simple webpage with a button that says “Clear”.
-
From the webhook’s detail page in the WorkOS dashboard, click the “Send test webhook” button:
-
A modal will appear with a pre-selected payload. Click the “Send test webhook” button at the bottom of the modal.
-
Navigate back to http://localhost:7001. You’ll see the payload appear!
Nice work! You just set up WorkOS webhooks for your example Java app!
If you get stuck while following the tutorial and aren't able to resolve the issue by reading our API reference for Webhooks or our guide on testing WorkOS webhooks locally, please reach out to us at support@workos.com so we can help!






