Async Webhook 도입을 통한 Keycloak-Backend 간 Event 동기화 지연 해소

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

Mr. Buch2026년 5월 14일6분intermediate

AI 요약

Context

Keycloak의 사용자 상태 변화가 외부 시스템(CRM, Billing 등)에 즉시 반영되지 않는 데이터 불일치 문제 발생. Admin API 폴링으로 인한 서버 부하 증가 및 DB 직접 참조에 따른 스키마 의존성 및 유지보수 비용 상승이라는 한계점에 직면함.

Keycloak SPI 기반 Event Listener를 구현하여 사용자 이벤트 발생 시 즉각적인 HTTP POST 송신 구조 설계
Backend 응답 대기로 인한 사용자 경험 저하를 막기 위해 Background Thread Pool을 통한 비동기 처리 방식 채택
시스템 복잡도 최소화를 위해 Durable Queue를 배제하고, 1s-2s-3s 간격의 Short Backoff 기반 최대 3회 재시도 로직 적용
Client UUID 기반의 Attribute 설정을 통해 서비스별 개별 Webhook Endpoint 및 API Key 관리 체계 구축
REGISTER_ERROR 이벤트를 포함하여 온보딩 단계의 드롭오프 분석이 가능한 데이터 파이프라인 확보

실천 포인트

1. 외부 시스템 연동 시 동기적 API 호출이 메인 프로세스의 성능 병목을 유발하는지 검토

2. 데이터 정밀도가 극도로 중요하지 않은 경우, 복잡한 Message Queue 대신 단순 Retry 메커니즘으로 인프라 오버헤드 제거 고려

3. 외부 라이브러리/플러그인 설정 시 Admin API를 통한 원자적 업데이트(Get-Modify-Put) 절차 준수 여부 확인

태그