웹훅을 알림 시스템으로 연결하는 방법

웹훅을 알림 시스템으로 연결하는 방법

Scope

핵심 질문

여러 애플리케이션의 이벤트를 webhook으로 받아 하나의 알림 시스템에 전달하려면 어떤 구조가 안정적인가?

Research

핵심 근거

• Webhook sender와 notification provider 사이에 작은 adapter를 두면 서비스별 payload 차이를 흡수할 수 있다.
• 인증, signature 검증, retry, idempotency가 중요하다.
• 알림 전송 실패가 원래 이벤트 처리 transaction을 막지 않도록 비동기 queue를 둘 수 있다.

Draft

Webhook 기반 알림 구조는 이벤트를 발생시키는 서비스와 실제 알림 채널을 분리하는 것이 핵심이다.

Adapter

각 서비스의 webhook payload를 공통 event 형식으로 변환한다. title, body, severity, source, link 정도의 공통 schema가 있으면 Discord, Telegram, push service 등으로 쉽게 전달할 수 있다.

인증

공개 endpoint라면 secret header나 HMAC signature를 검증해 임의 사용자가 알림을 보내지 못하게 해야 한다.

Retry와 중복

알림 provider가 일시적으로 실패할 수 있다. 재시도 시 같은 메시지가 여러 번 전송되지 않도록 event ID를 이용한 중복제거가 유용하다.

비동기화

중요한 원래 작업이 알림 API 응답을 기다리지 않도록 queue에 event를 넣고 별도 worker가 전송할 수 있다.

핵심

Webhook을 직접 채널마다 연결하기보다 공통 event adapter를 하나 두면 알림 경로를 변경하고 확장하기 쉬워진다.