웹훅: 아키텍처 변경에 대한 실시간 알림

지난주 한 팀이 Archyl에서 핵심 시스템의 이름을 변경했다는 이야기를 들었습니다 — C4 모델 전체에서 "UserService"를 "AccountService"로 바꾸고, 관계를 업데이트하고, ADR을 다시 작성했습니다. 깔끔하고 꼼꼼한 작업이었습니다. 문제는? 해당 시스템에 의존하던 플랫폼 팀이 나흘 뒤에야 알게 됐다는 것입니다. 배포 파이프라인이 더 이상 존재하지 않는 이름을 참조하고 있었을 때였습니다.

아무도 알려주지 않았습니다. 누군가가 부주의했기 때문이 아니라 — 단지 그런 메커니즘이 없었을 뿐입니다. 아키텍처 문서는 보통 풀(pull) 모델입니다. 직접 다이어그램을 보러 갑니다. 직접 ADR을 읽으러 갑니다. 보러 가지 않으면 알 수 없습니다.

이것은 CI/CD 알림이 표준이 되기 전 소프트웨어 개발을 괴롭혔던 것과 같은 패턴입니다. 코드 변경은 예전에 main을 풀(pull)할 때 발견하는 것이었습니다. 오늘날에는 모든 머지, 모든 실패한 빌드, 모든 배포가 어딘가에 알림을 발생시킵니다. 아키텍처 변경도 같은 대우를 받을 자격이 있습니다.

아키텍처를 위한 푸시 알림

Archyl이 이제 웹훅을 지원합니다. C4 모델에서 무언가 변경되면 — 시스템이 생성되거나, 컨테이너가 삭제되거나, 관계가 업데이트되거나, 릴리스가 배포되면 — Archyl은 설정한 모든 엔드포인트로 HTTP POST를 전송하며, 정확히 무엇이 발생했는지 설명하는 JSON 페이로드를 포함합니다.

아이디어는 간단합니다: 아키텍처는 살아있는 시스템입니다. 사람과 도구는 배포 이벤트나 풀 리퀘스트 알림을 구독하는 것처럼 아키텍처의 변경을 구독할 수 있어야 합니다. "변경된 것이 있나요?"라고 묻는 대신, 답이 알아서 찾아옵니다.

44가지 이벤트 유형

모델의 절반만 커버하는 알림 시스템을 출시하고 싶지 않았습니다. 웹훅은 Archyl이 추적하는 모든 것에 대해 발생합니다:

C4 요소 — 시스템, 컨테이너, 컴포넌트, 코드 요소의 생성, 업데이트, 삭제. 아키텍처 모델의 핵심입니다.

관계 — 요소 간 연결이 생성, 수정 또는 제거될 때. 이것은 종종 가장 중요한 신호입니다 — 두 시스템 간의 새로운 의존성은 여러 팀이 알아야 하는 유형의 변경입니다.

ADR 및 문서 — 아키텍처 의사결정 기록과 프로젝트 문서의 생성, 업데이트, 삭제. 누군가 REST에서 gRPC로 마이그레이션하는 이유를 설명하는 새 ADR을 작성하면, 영향을 받는 사람들은 세 스프린트 후가 아니라 즉시 알아야 합니다.

플로우 — 사용자 및 시스템 플로우 변경. 새로운 플로우, 업데이트된 단계, 삭제된 플로우.

오버레이 — 다이어그램의 시각적 그룹화 변경.

릴리스 — 환경 전반의 배포 이벤트. 릴리스 관리와 결합하면 완전한 푸시 기반 배포 알림 파이프라인을 구현할 수 있습니다.

요청 — 아키텍처 변경 요청의 생성, 검토 또는 병합.

API 계약 및 이벤트 채널 — 아키텍처에 연결된 사양 변경 및 비동기 메시징 업데이트.

디스커버리 및 인사이트 — AI 기반 디스커버리 완료 및 새로운 아키텍처 인사이트.

총 44가지 이벤트 유형입니다. 관심 있는 것을 선택합니다 — 전부 구독하거나, 워크플로우에 중요한 다섯 가지 이벤트만 구독할 수 있습니다.

작동 방식

웹훅 설정은 약 30초면 됩니다.

이름을 지정합니다 (설명적인 것으로 — "Slack 알림", "감사 로그 동기화", "CI 트리거"). URL을 입력합니다 — POST 요청을 수신할 수 있는 모든 HTTP 엔드포인트입니다. 선택적으로 서명 검증을 위한 시크릿을 설정합니다. 그리고 어떤 이벤트가 트리거해야 하는지 선택합니다.

웹훅의 범위를 특정 프로젝트로 지정할 수도 있습니다. 모든 프로젝트의 모든 변경에 대해 발생하는 조직 전체 웹훅은 감사 로깅에 유용합니다. 결제 시스템의 릴리스 이벤트에만 발생하는 프로젝트 범위 웹훅은 해당 시스템을 담당하는 팀에 유용합니다.

일치하는 이벤트가 발생하면 Archyl은 다음을 포함하는 JSON 페이로드와 함께 URL로 HTTP POST를 전송합니다:

  • 이벤트 유형 — 44가지 이벤트 중 어떤 것이 이 전달을 트리거했는지
  • 엔티티 — 변경된 요소의 전체 세부 정보
  • 액터 — 누가 변경했는지 (사용자 ID, 이름, 이메일)
  • 프로젝트 — 어떤 프로젝트에서 발생했는지
  • 타임스탬프 — 변경이 발생한 시점
  • 조직 — 어떤 조직에 속하는지

페이로드는 변경에 대응하는 데 필요한 모든 것을 제공합니다 — 표시하거나, 로깅하거나, 파이프라인을 트리거하거나, 다른 시스템에 동기화할 수 있습니다.

보안: HMAC-SHA256 서명

모든 웹훅 요청에는 sha256=<hex digest> 형식의 X-Archyl-Signature 헤더가 포함됩니다 — 시크릿을 사용하여 원시 요청 본문의 HMAC-SHA256 해시를 계산한 값입니다. 또한 X-Archyl-Event (이벤트 유형)와 User-Agent: Archyl-Webhook/1.0 헤더가 함께 전송되므로 요청의 출처를 식별할 수 있습니다.

수신 측에서는 sha256= 접두사를 제거하고, 시크릿 사본을 사용하여 원시 본문 바이트에 대해 HMAC-SHA256 해시를 다시 계산한 뒤, 상수 시간 비교(constant-time comparison)를 사용하여 비교합니다. 일치하면 요청은 진본입니다. 일치하지 않으면 누군가가 위조된 이벤트를 보내고 있는 것입니다.

이것은 GitHub, Stripe, 그리고 대부분의 웹훅 제공자가 사용하는 것과 동일한 서명 방식입니다. 간단하고, 잘 알려져 있으며, 어떤 언어로든 쉽게 구현할 수 있습니다. OAuth 플로우도, 토큰 교체도, 인증서 관리도 필요 없습니다. 공유 시크릿과 해시만 있으면 됩니다. Go, Node.js, Python의 전체 검증 예제는 웹훅 문서를 참고하세요.

시크릿을 설정하지 않으면 서명 헤더가 생략됩니다. VPN 뒤의 내부 엔드포인트에는 괜찮습니다. 인터넷에 노출된 것에는 권장하지 않습니다.

이것으로 만들 수 있는 것

가장 확실한 사용 사례는 채팅 알림입니다. Slack, Microsoft Teams, Discord 모두 수신 웹훅을 지원합니다 — 해당 URL을 Archyl에 붙여넣고, 관심 있는 이벤트를 선택하면 아키텍처 변경이 채널에 나타나기 시작합니다. 새 시스템이 추가되었습니다. ADR이 승인되었습니다. 프로덕션에 릴리스가 배포되었습니다. 팀이 Archyl을 열지 않고도 볼 수 있습니다.

하지만 알림은 시작에 불과합니다.

외부 시스템 동기화 — 아키텍처 변경을 CMDB, 내부 위키 또는 서비스 카탈로그에 푸시합니다. Archyl에서 컨테이너 이름이 변경되면 서비스 카탈로그가 자동으로 업데이트됩니다.

CI/CD 파이프라인 트리거 — 아키텍처 변경 요청이 병합되면 인프라 설정을 재생성하거나, Terraform 모듈을 업데이트하거나, 실제 배포가 문서화된 아키텍처와 일치하는지 검증하는 파이프라인을 시작합니다.

감사 추적 — 모든 이벤트를 외부 로깅 시스템 — Elasticsearch, Splunk, 단순한 추가 전용 데이터베이스 — 으로 전달합니다. Archyl의 7일간의 전달 이력은 디버깅에 유용합니다. 영구적인 외부 로그는 컴플라이언스에 유용합니다.

커스텀 대시보드 — 아키텍처 이벤트에 실시간으로 반응하는 내부 대시보드를 구축합니다. 아키텍처가 얼마나 자주 변경되는지, 어떤 팀이 가장 활발한지, 어떤 시스템이 가장 변동이 큰지 추적합니다.

핵심은 웹훅이 Archyl을 이벤트 소스로 변환한다는 것입니다. 아키텍처 모델이 다른 시스템이 구독하고, 반응하고, 그 위에 구축할 수 있는 무언가가 됩니다.

전달 추적

모든 웹훅 전달이 기록됩니다. 모든 웹훅에 대한 전체 이력을 볼 수 있습니다: 어떤 이벤트가 트리거했는지, 전송된 요청 페이로드, 응답 상태 코드, 응답 본문, 전송 및 응답 도착 시간.

전달 기록은 7일간 보관됩니다. 통합 문제를 디버깅하기에 충분히 길고, 엔드포인트의 응답 본문을 무기한 저장하지 않을 만큼 짧습니다.

전달이 실패하면 — 서버의 500 응답, 타임아웃, DNS 확인 오류 — 빨간색 상태로 표시됩니다. 오류를 확인하고, 엔드포인트를 수정한 후 한 번의 클릭으로 재시도할 수 있습니다. 재시도는 동일한 페이로드를 그대로 전송하므로 엔드포인트는 처음 성공한 것처럼 원래 이벤트를 처리합니다.

자동 재시도는 없습니다. 지수 백오프를 고려했지만, 실제로 대부분의 웹훅 실패는 일시적(서버가 재시작 중)이거나 구조적(URL이 잘못됨)입니다. 일시적 실패의 경우 수동 재시도 버튼이 백오프를 기다리는 것보다 빠릅니다. 구조적 실패의 경우 자동 재시도는 노이즈만 생성합니다.

시작하기

  1. 조직 설정 > 웹훅으로 이동합니다
  2. 웹훅 생성을 클릭합니다
  3. 이름을 입력하고, 엔드포인트 URL을 붙여넣고, 시크릿을 설정합니다
  4. 구독하려는 이벤트를 선택합니다
  5. 선택적으로 특정 프로젝트로 필터링합니다
  6. 테스트 전송을 클릭하여 엔드포인트가 페이로드를 수신하는지 확인합니다
  7. 저장하면 바로 활성화됩니다

테스트 전달은 샘플 페이로드와 함께 핑 이벤트를 전송하여 엔드포인트에 접근 가능한지, 시크릿이 올바르게 설정되었는지, 핸들러가 JSON을 예상대로 처리하는지 확인할 수 있습니다. 실제 이벤트를 구독하기 전에 이 작업을 수행하세요.

이벤트 스트림으로서의 아키텍처

우리는 정적 산출물이 아닌 아키텍처 문서의 버전을 만들어 왔습니다 — 개발 워크플로우의 살아있고 연결된 일부입니다. 마켓플레이스 통합은 외부 데이터를 아키텍처 안으로 가져옵니다. 웹훅은 아키텍처 데이터를 도구 밖으로 내보냅니다.

이 조합은 강력합니다. 아키텍처 작업 공간은 단순히 다이어그램을 보러 가는 곳이 아닙니다. 모니터링 도구로부터 운영 데이터를 받고, 커뮤니케이션 및 자동화 도구로 변경 이벤트를 내보내는 허브입니다. 데이터가 양방향으로 흐릅니다.

아무도 보지 않는 아키텍처 문서는 쓸모없습니다. 중요한 순간에 알려주는 아키텍처 문서 — 그것이 인프라입니다.

다른 기능이 아키텍처를 워크플로우에 어떻게 연결하는지 보고 싶으신가요? 다이어그램에 라이브 데이터를 가져오는 마켓플레이스 통합이나, C4 모델 전반의 배포를 추적하는 릴리스 관리를 확인해 보세요.