Skip to content
This repository was archived by the owner on Jan 9, 2026. It is now read-only.

Latest commit

 

History

History

java-webhooks-example

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 

README.md

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!

Prerequisites

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)

Clone the Java app

  1. In your CLI, navigate to the directory into which you want to clone the Java example app git repo:
$ cd ~/Desktop
  1. 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
  1. Navigate to the cloned repo:
$ cd java-example-applications/

Securely store the environment variables

  1. 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.

Screenshot of the WorkOS dashboard showing where to locate the API key

Screenshot of the WorkOS dashboard showing where to locate the Client ID

  1. Create a .env file in the java-example-applications/ directory to store the environment variables:
$ touch .env
  1. 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_here

The .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.

Start an ngrok session

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.

  1. Start a new ngrok session by running this command from the java-example-applications/ directory:
$ ngrok http 7001

You’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.

Set Up a WorkOS Endpoint

  1. Log into the WorkOS Dashboard and navigate to the Webhooks section:

A screenshot of the WorkOS dashboard

  1. 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:

A screenshot of the webhooks setup modal

The cloned application is listening for webhook requests at http://localhost:7001/webhooks

Set Up Webhooks Secret

  1. 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:

A screenshot of the webhooks detail page

  1. Then locate and copy the secret key:

A screenshot of the secret key in the webhooks dashboard

  1. 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

Test the integration

  1. 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
  1. Navigate to http://localhost:7001. You’ll see a simple webpage with a button that says “Clear”.

  2. From the webhook’s detail page in the WorkOS dashboard, click the “Send test webhook” button:

A screenshot of the "send test webhook" button

  1. A modal will appear with a pre-selected payload. Click the “Send test webhook” button at the bottom of the modal.

  2. 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!

Need help?

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!