A Keycloak extension that sends webhook notifications to external APIs when specific user events occur in Keycloak.

This extension integrates with Keycloak's event system to capture user-related events such as registration, login, logout, and password resets. When these events occur, the extension sends HTTP POST requests with user data to a configured webhook endpoint.

Key features:

• Listens for REGISTER, REGISTER_ERROR, LOGIN, LOGOUT, RESET_PASSWORD, VERIFY_EMAIL, UPDATE_EMAIL, and DELETE_ACCOUNT events
• Sends structured JSON payloads with comprehensive user information
• Supports authentication with API keys
• Implements retry logic with exponential backoff
• Configurable through Keycloak client attributes

• Java 17 or higher
• Keycloak 26.2.5 or a compatible version
• Maven for building the project

1. Build the extension:

   make build

2. Copy the generated JAR file to Keycloak's providers directory:

   cp target/keycloak-client-webhook.jar /path/to/keycloak/providers/

3. Restart Keycloak to load the extension.

1. Log in to the Keycloak Admin Console
2. Navigate to your realm
3. Go to Realm Settings → Events
4. In the "Event Listeners" field, add brew-event-webhook
5. Click "Save"

The webhook URL and API key are configured at the client level. For each client that should trigger webhooks:

1. Navigate to Clients in the Keycloak Admin Console
2. Select the client you want to configure
3. Go to the Attributes tab
4. Add the following attributes:
   • api.url: The URL of your webhook endpoint (e.g., https://your-api.example.com/webhooks/keycloak)
   • api.key: The API key or token for authenticating with your webhook endpoint
   • disable.autologin: Set to "true" to prevent automatic login after registration (useful when additional verification steps are required)

The extension sends a JSON payload with the following structure:

{
  "type": "LOGIN",
  "user_id": "f:6f8df73e-9c42-4f8b-b3a1-c1d9bcb45f0b",
  "user_name": "john.doe",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "email_verified": true,
  "created_timestamp": 1621459200000,
  "user_ip": "192.168.1.1",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
}

The extension currently listens for the following Keycloak events:

• REGISTER: When a new user registers
• REGISTER_ERROR: When a user registration fails
• LOGIN: When a user logs in
• LOGOUT: When a user logs out
• RESET_PASSWORD: When a user resets their password
• VERIFY_EMAIL: When a user verifies their email address
• UPDATE_EMAIL: When a user's email address is updated
• DELETE_ACCOUNT: When a user account is deleted

1. Verify the event listener is properly enabled in the realm settings
2. Check that the client has the correct api.url and api.key attributes
3. Examine Keycloak server logs for any error messages
4. Ensure your webhook endpoint is accessible from the Keycloak server

The extension implements retry logic with exponential backoff. If there are temporary connection issues, it will retry up to 3 times with increasing delays. Since webhook calls are executed asynchronously, these retries happen in the background and don't affect Keycloak's performance or user experience.