{"id":21463047,"url":"https://github.com/vymalo/keycloak-webhook","last_synced_at":"2025-07-15T03:31:22.548Z","repository":{"id":153086085,"uuid":"628094839","full_name":"vymalo/keycloak-webhook","owner":"vymalo","description":"Event-based Webhook plugin for Keycloak","archived":false,"fork":false,"pushed_at":"2024-02-29T13:00:38.000Z","size":104,"stargazers_count":13,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-02-29T14:26:36.734Z","etag":null,"topics":["events","keycloak","keycloak-event-provider","keycloak-spi","kotlin","kotlin-server","openapi","openapi3","webhook"],"latest_commit_sha":null,"homepage":"https://blog.ssegning.com","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vymalo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":["vymalo","stephane-segning"]}},"created_at":"2023-04-14T22:47:31.000Z","updated_at":"2024-02-29T14:26:37.605Z","dependencies_parsed_at":null,"dependency_job_id":"0e6d4477-b435-4fae-8e14-fcd2ce8298a3","html_url":"https://github.com/vymalo/keycloak-webhook","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vymalo%2Fkeycloak-webhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vymalo%2Fkeycloak-webhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vymalo%2Fkeycloak-webhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vymalo%2Fkeycloak-webhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vymalo","download_url":"https://codeload.github.com/vymalo/keycloak-webhook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226012837,"owners_count":17559774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["events","keycloak","keycloak-event-provider","keycloak-spi","kotlin","kotlin-server","openapi","openapi3","webhook"],"created_at":"2024-11-23T07:18:25.896Z","updated_at":"2025-07-15T03:31:22.538Z","avatar_url":"https://github.com/vymalo.png","language":"Kotlin","funding_links":["https://github.com/sponsors/vymalo","https://github.com/sponsors/stephane-segning"],"categories":["Community Extensions"],"sub_categories":[],"readme":"# Keycloak Webhook Plugin\n\nA modular Keycloak event listener plugin that triggers webhooks whenever specific events (like login, registration, or\nlogout) occur in Keycloak. This project leverages a multi-module design so you can choose which transport provider (HTTP,\nAMQP, or Syslog) to deploy based on your needs.\n\n| Keycloak Version | Plugin Version |\n| ---------------- | -------------- |\n| 24               | ✅ 0.9.1       |\n| 25               | ✅ 0.9.1       |\n| 26               | ✅ 0.9.1       |\n\n---\n\n## 1. What It Is\n\nThe Keycloak Webhook Plugin consists of four modules:\n\n- **Core Module (`keycloak-webhook-provider-core`)**  \n  Contains common SPI interfaces, shared models, and helper utilities.\n\n- **AMQP Provider (`keycloak-webhook-provider-amqp`)**  \n  Implements webhook notifications over AMQP (e.g., RabbitMQ). If the AMQP dependency is present on the classpath, this\n  provider is loaded automatically.\n\n- **HTTP Provider (`keycloak-webhook-provider-http`)**  \n  Implements webhook notifications over HTTP. This provider uses OpenAPI-generated clients to ensure compliance with the\n  target API.\n\n- **Syslog Provider (`keycloak-webhook-provider-syslog`)**  \n  Implements webhook notifications over Syslog (TCP/UDP). Supports RFC 3164 and RFC 5424 message formats.\n\nKeycloak uses Java's `ServiceLoader` mechanism to conditionally load these providers at runtime if their JARs (and\ndependencies) are available.\n\n---\n\n## 2. How to Use It\n\n### Downloading the Plugins\n\nDownload the latest release artifacts (shaded JARs) from the GitHub releases page. For example, using `curl`:\n\n```bash\n# Replace \u003cversion\u003e with the desired release version.\n\ncurl -L -o keycloak-webhook-provider-core.jar https://github.com/vymalo/keycloak-webhook/releases/download/v\u003cversion\u003e/keycloak-webhook-provider-core-\u003cversion\u003e-all.jar\ncurl -L -o keycloak-webhook-provider-amqp.jar https://github.com/vymalo/keycloak-webhook/releases/download/v\u003cversion\u003e/keycloak-webhook-provider-amqp-\u003cversion\u003e-all.jar\ncurl -L -o keycloak-webhook-provider-http.jar https://github.com/vymalo/keycloak-webhook/releases/download/v\u003cversion\u003e/keycloak-webhook-provider-http-\u003cversion\u003e-all.jar\ncurl -L -o keycloak-webhook-provider-syslog.jar https://github.com/vymalo/keycloak-webhook/releases/download/v\u003cversion\u003e/keycloak-webhook-provider-syslog-\u003cversion\u003e-all.jar\n```\n\n### a. Docker\n\nWhen running Keycloak in Docker, mount the downloaded JARs into Keycloak's providers directory. For example, in your\n`docker-compose.yaml`:\n\n```yaml\nservices:\n  keycloak:\n    image: quay.io/keycloak/keycloak:26.1.3\n    ports:\n      - \"9100:9100\"\n    environment:\n      # HTTP Provider Configuration\n      WEBHOOK_HTTP_BASE_PATH: \"http://prism:4010\"\n      WEBHOOK_HTTP_AUTH_USERNAME: \"admin\"\n      WEBHOOK_HTTP_AUTH_PASSWORD: \"password\"\n      # AMQP Provider Configuration\n      WEBHOOK_AMQP_HOST: rabbitmq\n      WEBHOOK_AMQP_USERNAME: username\n      WEBHOOK_AMQP_PASSWORD: password\n      WEBHOOK_AMQP_PORT: 5672\n      WEBHOOK_AMQP_VHOST: \"/\"\n      WEBHOOK_AMQP_EXCHANGE: keycloak\n      WEBHOOK_AMQP_SSL: \"no\"\n      # Syslog Provider Configuration\n      WEBHOOK_SYSLOG_PROTOCOL: udp\n      WEBHOOK_SYSLOG_HOSTNAME: keycloak\n      WEBHOOK_SYSLOG_APP_NAME: Keycloak\n      WEBHOOK_SYSLOG_FACILITY: USER\n      WEBHOOK_SYSLOG_SEVERITY: INFORMATIONAL\n      WEBHOOK_SYSLOG_SERVER_HOSTNAME: syslog-ng\n      WEBHOOK_SYSLOG_SERVER_PORT: 5514\n      WEBHOOK_SYSLOG_MESSAGE_FORMAT: RFC_5425\n      # Keycloak Admin Credentials\n      KEYCLOAK_ADMIN: admin\n      KEYCLOAK_ADMIN_PASSWORD: password\n      KC_HTTP_PORT: 9100\n      KC_METRICS_ENABLED: \"true\"\n      KC_LOG_CONSOLE_COLOR: \"true\"\n      KC_HEALTH_ENABLED: \"true\"\n    entrypoint: /bin/sh\n    command:\n      - -c\n      - |\n        set -ex\n        # Copy all plugin JARs from the mounted volume into Keycloak's providers folder\n        cp /tmp/plugins/*.jar /opt/keycloak/providers\n        /opt/keycloak/bin/kc.sh start-dev --import-realm\n    volumes:\n      - ./plugins:/tmp/plugins:ro # Place your downloaded JARs in this folder\n      - ./.docker/keycloak-config/:/opt/keycloak/data/import/:ro\n```\n\n### b. Kubernetes\n\nIn Kubernetes, you can use an init container to download the plugin JARs from GitHub artifacts and copy them into\nKeycloak's providers folder. For example:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: keycloak\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: keycloak\n  template:\n    metadata:\n      labels:\n        app: keycloak\n    spec:\n      volumes:\n        - name: providers-volume\n          emptyDir: {}\n      initContainers:\n        - name: download-plugins\n          image: curlimages/curl:8.1.2\n          command:\n            - sh\n            - -c\n            - |\n              mkdir -p /plugins\n              # Download the plugins from GitHub releases (update the URLs accordingly)\n              curl -L -o /plugins/keycloak-webhook-provider-core.jar https://github.com/vymalo/keycloak-webhook/releases/download/v\u003cversion\u003e/keycloak-webhook-provider-core-\u003cversion\u003e-all.jar\n              curl -L -o /plugins/keycloak-webhook-provider-amqp.jar https://github.com/vymalo/keycloak-webhook/releases/download/v\u003cversion\u003e/keycloak-webhook-provider-amqp-\u003cversion\u003e-all.jar\n              curl -L -o /plugins/keycloak-webhook-provider-http.jar https://github.com/vymalo/keycloak-webhook/releases/download/v\u003cversion\u003e/keycloak-webhook-provider-http-\u003cversion\u003e-all.jar\n              curl -L -o /plugins/keycloak-webhook-provider-syslog.jar https://github.com/vymalo/keycloak-webhook/releases/download/v\u003cversion\u003e/keycloak-webhook-provider-syslog-\u003cversion\u003e-all.jar\n              cp /plugins/*.jar /providers/\n          volumeMounts:\n            - name: providers-volume\n              mountPath: /providers\n      containers:\n        - name: keycloak\n          image: quay.io/keycloak/keycloak:26.1.3\n          env:\n            - name: WEBHOOK_HTTP_BASE_PATH\n              value: \"http://prism:4010\"\n            - name: WEBHOOK_HTTP_AUTH_USERNAME\n              value: \"admin\"\n            - name: WEBHOOK_HTTP_AUTH_PASSWORD\n              value: \"password\"\n            - name: WEBHOOK_AMQP_HOST\n              value: \"rabbitmq\"\n            - name: WEBHOOK_AMQP_USERNAME\n              value: \"username\"\n            - name: WEBHOOK_AMQP_PASSWORD\n              value: \"password\"\n            - name: WEBHOOK_AMQP_PORT\n              value: \"5672\"\n            - name: WEBHOOK_AMQP_VHOST\n              value: \"/\"\n            - name: WEBHOOK_AMQP_EXCHANGE\n              value: \"keycloak\"\n            - name: WEBHOOK_AMQP_SSL\n              value: \"no\"\n            - name: WEBHOOK_SYSLOG_PROTOCOL\n              value: \"udp\"\n            - name: WEBHOOK_SYSLOG_SERVER_HOSTNAME\n              value: \"syslog-ng\"\n            - name: WEBHOOK_SYSLOG_SERVER_PORT\n              value: \"5514\"\n          volumeMounts:\n            - name: providers-volume\n              mountPath: /opt/keycloak/providers\n```\n\n---\n\n## 3. Environment Variables\n\n### HTTP Provider\n\n- **`WEBHOOK_HTTP_BASE_PATH`**  \n  The endpoint URL where webhook requests are sent.\n\n- **`WEBHOOK_HTTP_AUTH_USERNAME` (optional)**  \n  Basic auth username.\n\n- **`WEBHOOK_HTTP_AUTH_PASSWORD` (optional)**  \n  Basic auth password.\n\n### AMQP Provider\n\n- **`WEBHOOK_AMQP_HOST`**  \n  RabbitMQ server hostname.\n\n- **`WEBHOOK_AMQP_USERNAME`**  \n  Username for RabbitMQ.\n\n- **`WEBHOOK_AMQP_PASSWORD`**  \n  Password for RabbitMQ.\n\n- **`WEBHOOK_AMQP_PORT`**  \n  Port for RabbitMQ.\n\n- **`WEBHOOK_AMQP_VHOST` (optional)**  \n  Virtual host for RabbitMQ.\n\n- **`WEBHOOK_AMQP_EXCHANGE`**  \n  Exchange name for RabbitMQ.\n\n- **`WEBHOOK_AMQP_SSL` (optional)**  \n  `\"yes\"` or `\"no\"`, indicating if SSL is enabled.\n\n### Syslog Provider\n\n- **`WEBHOOK_SYSLOG_PROTOCOL`**  \n  `\"TCP\"` or `\"UDP\"` protocol for Syslog communication.\n\n- **`WEBHOOK_SYSLOG_HOSTNAME`**  \n  Hostname of the Keycloak instance.\n\n- **`WEBHOOK_SYSLOG_APP_NAME`**  \n  Application name for Syslog messages.\n\n- **`WEBHOOK_SYSLOG_FACILITY`**  \n  Syslog facility (e.g., USER, DAEMON, AUTH).\n\n- **`WEBHOOK_SYSLOG_SEVERITY`**  \n  Syslog severity level (e.g., INFORMATIONAL, WARNING, ERROR).\n\n- **`WEBHOOK_SYSLOG_SERVER_HOSTNAME`**  \n  Hostname of the Syslog server.\n\n- **`WEBHOOK_SYSLOG_SERVER_PORT`**  \n  Port of the Syslog server.\n\n- **`WEBHOOK_SYSLOG_MESSAGE_FORMAT`**  \n  `\"RFC_3164\"`, `\"RFC_5424\"` or `\"RFC_5425\"` message format.\n\n- **`WEBHOOK_EVENTS_TAKEN` (optional)**  \n  A comma-separated list of Keycloak events (e.g., `\"LOGIN,REGISTER,LOGOUT\"`) that should trigger webhooks. If not\n  specified, all events are processed.\n\n---\n\n## 4. Architecture\n\nThe architecture of the Keycloak Webhook Plugin is illustrated using a Mermaid diagram below:\n\n```mermaid\ngraph TD\n    A[\"Keycloak (Event Source)\"]\n    B[\"ServiceLoader (SPI)\"]\n    C[Core Module]\n    D[HTTP Provider]\n    E[AMQP Provider]\n    F[Syslog Provider]\n    G[External HTTP Server]\n    H[RabbitMQ Broker]\n    I[Syslog Server]\n    A --\u003e B\n    B --\u003e C\n    C --\u003e D\n    C --\u003e E\n    C --\u003e F\n    D --\u003e G\n    E --\u003e H\n    F --\u003e I\n```\n\n- **Core Module:**  \n  Provides common interfaces, models, and utilities.\n\n- **Provider Modules:**  \n  Implement specific webhook delivery mechanisms (HTTP, AMQP, or Syslog) and are conditionally loaded if their JARs are present.\n\n- **ServiceLoader:**  \n  Uses Java's SPI to discover and load the providers.\n\n- **External Systems:**  \n  Webhook notifications are sent to an HTTP server, published to a RabbitMQ broker, or forwarded to a Syslog server.\n\n---\n\n## 5. Contribute\n\nWe welcome contributions! To get started:\n\n1. **Fork the Repository:**  \n   Create your own fork of the project on GitHub.\n\n2. **Set Up Your Development Environment:**\n\n- Clone your fork locally.\n- Ensure you have JDK 17 and Gradle installed.\n- Build the project using:\n  ```bash\n  ./gradlew clean shadow\n  ```\n\n3. **Follow Code Conventions:**\n\n- Keep the code style consistent with the existing modules.\n- Write tests where applicable.\n- Update the README and documentation if your changes require it.\n\n4. **Submit a Pull Request:**  \n   Open a pull request with your proposed changes. Please include a detailed description and reference any related\n   issues.\n\n5. **Join Discussions:**  \n   Use GitHub issues to discuss ideas, report bugs, or ask for help.\n\n---\n\nThis modular and flexible design allows you to deploy only the providers you need while keeping the project maintainable\nand extensible. Happy coding!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvymalo%2Fkeycloak-webhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvymalo%2Fkeycloak-webhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvymalo%2Fkeycloak-webhook/lists"}