Repository files navigation

A Keycloak extension that listens for user events (create/register) and forwards them to your webhook.

# Clone the repositorygit clone https://github.com/cevher/keycloak-custom-event-listener.gitcd keycloak-custom-event-listener# Set up environment variablescp .env.example .env# Edit .env and set your WEBHOOK_URL# Build the extensionmvn clean package# Copy JAR to Keycloak providerscp target/custom-event-listener.jar providers/# or### Attach keycloak dockerVolume (already in docker-compose file)```yaml    volumes:      - ../../../target/custom-event-listener.jar://opt/jboss/keycloak/standalone/deployments/custom-event-listener.jar

docker-compose up -d

# Copy example environment filecp .env.example .env# Edit .env file and update the WEBHOOK_URL# Example:# WEBHOOK_URL=https://your-webhook-url.com/endpoint

mvn clean package

# Create providers directory if it doesn't existmkdir -p keycloak/providers# Copy JAR to providers directorycp target/custom-event-listener.jar keycloak/providers/

docker-compose up -d

1. Access Keycloak Admin Console (default:http://localhost:8080)
2. Login as admin (default credentials: admin/admin)
3. Navigate to:
   • Events
   • Event configs

• Events

4. Add "custom-event-listener"

5. Save

1. Ensure your webhook endpoint is publicly accessible.

2. Configure theWEBHOOK_URL in thedocker-compose.yaml file:

   services:keycloak:image: quay.io/keycloak/keycloak:latestenvironment:- WEBHOOK_URL=https://your-webhook-url.com/endpointports:- "8080:8080"volumes:- ./providers:/opt/keycloak/providers

3. Test the webhook by sending a sample event from Keycloak or using a tool like Postman to ensure it receives the data correctly.

4. Monitor your webhook endpoint for incoming requests to verify that events are being forwarded successfully.

1. Users
2. Add User
3. Fill in the required fields:
   • Username (required)
   • Email
   • First Name
   • Last Name
4. Click "Create" to save the new user

5. Check your webhook endpoint for the notification

1. Go tohttp://localhost:8080/realms/master/account/#/
2. Click "Register" or navigate to the registration page
3. Fill out the registration form and submit

sequenceDiagram    participant User    participant Keycloak    participant EventListener    participant WebhookEndpoint    User->>Keycloak: Registers or Creates an Account    Keycloak-->>EventListener: Emits User Registration Event    EventListener->>WebhookEndpoint: Sends Event Data    WebhookEndpoint-->>EventListener: Acknowledgement

You can use services like webhook.site or RequestBin to test the webhook integration:

1. Get a temporary webhook URL from webhook.site
2. Add it to your .env file
3. Create a user in Keycloak
4. Check the webhook.site dashboard for the event data

# Stop and remove containersdocker-compose down# Remove volumes (optional)docker-compose down -vdocker volume ls| grep keycloak| awk'{print $2}'| xargs docker volume rm

1. Webhook not receiving events

   • Check if the WEBHOOK_URL in .env is correct
   • Verify the event listener is enabled in Keycloak
   • Check Keycloak logs for any errors

2. Build failures

   • Ensure Maven is installed
   • Check Java version (requires Java 11+)

# View Keycloak logsdocker-compose logs -f keycloak

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

Apache-2.0 license