Keycloak Webhooks: Bridging the Auth Gap in Modern Tech Stacks

Keycloak Knows. Why Doesn’t The Rest Of Your Stack?

Keycloak Webhook is a custom Service Provider Interface (SPI) extension designed to synchronize identity events with external systems. It triggers background HTTP POST requests for eight critical user actions, ensuring registration and deletion data remains consistent across CRMs and billing platforms.

Why This Matters

In theory, identity management systems serve as the single source of truth, but in reality, downstream services like CRMs and billing systems often fall out of sync due to reliance on manual updates or brittle API polling. This creates a disconnect where Keycloak maintains accurate state while peripheral systems fail to account for deleted users or new signups. Using the Keycloak Admin API for polling introduces data latency and unnecessary load, while direct database queries risk breakage during schema updates, leading to critical business failures such as charging deleted accounts. Implementation of a push-based event model ensures data consistency without compromising the performance of the authentication server.

Key Insights

• Asynchronous background execution: The extension hands off HTTP POST requests to a separate thread pool to prevent blocking Keycloak’s main user flow or causing latency for the end-user.
• Configurable retry logic: Failed webhook attempts trigger three retries with incremental backoff (1s, 2s, 3s) to handle temporary backend outages before logging a final failure.
• Granular event support: The SPI captures specific actions including REGISTER, REGISTER_ERROR, LOGIN, LOGOUT, RESET_PASSWORD, VERIFY_EMAIL, UPDATE_EMAIL, and DELETE_ACCOUNT.
• Client-specific configuration: Webhook endpoints and API keys are stored as custom attributes (api.url and api.key) within individual Keycloak client representations rather than a global config.
• Zero-config deployment: The JAR file auto-registers as a Keycloak SPI on startup and requires manual activation in the Realm Settings Event Listeners field.

Working Examples

Standard webhook payload delivered via HTTP POST

{
"type": "REGISTER",
"user_id": "6f8df73e-9c42-4f8b-b3a1-c1d9bcb45f0b",
"user_name": "john_doe",
"email": "[email protected]",
"first_name": "John",
"last_name": "Doe",
"email_verified": false,
"created_timestamp": 1715726400000,
"user_ip": "203.0.113.45",
"user_agent": "Mozilla/5.0...",
"delete_by_admin": false,
"user_roles": ["user"],
"organizations": [
{
"id": "org-123",
"name": "ACME Corporation",
"alias": "acme"
}
]
}

Updating Keycloak client attributes via Admin API

curl -X PUT \
"https://your-keycloak/admin/realms/{realm}/clients/{client-uuid}" \
-H "Authorization: Bearer {access_token}" \
-H "Content-Type: application/json" \
-d '{
"attributes": {
"api.url": "https://yourapi.com/webhooks/keycloak",
"api.key": "your-secret-token"
}
}'

Practical Applications

• CRM Synchronization: Automatically push registration data to platforms like Salesforce to prevent manual data entry errors and stale user records.
• Billing Management: Trigger account deletion events to stop recurring charges immediately when a user closes their account, avoiding compliance and billing issues.
• Onboarding Analytics: Monitor REGISTER_ERROR events to track failed signups and debug friction points in the user onboarding funnel in real-time.
• Pitfall: Updating clients via PUT without first performing a GET will replace the entire object and wipe out existing client configuration.

References:

• https://dev.to/mr_buch/keycloak-knows-why-doesnt-the-rest-of-your-stack-4ikj