서클CI에 웹후크 설정 방법은 무엇인가요?

아래는 서클CI(CircleCI)에서 웹훅(Webhook)을 설정·운영할 때 자주 묻는 질문(FAQ)과 그에 대한 답변입니다.

1. Q: CircleCI 웹훅이란 무엇인가요?
A: CircleCI 웹훅은 빌드·테스트·배포 같은 파이프라인 이벤트가 발생할 때 지정한 외부 URL(엔드포인트)로 JSON 페이로드를 전송해주는 기능입니다. 이를 통해 별도 시스템(챗봇, 모니터링 도구, 내부 서비스 등)과 자동 연동할 수 있습니다.

2. Q: 어떤 상황에서 웹훅을 사용하나요?
A:
- 빌드 실패 혹은 성공을 슬랙, 팀즈, 이메일로 실시간 알림
- 커스텀 대시보드에 빌드 현황 업데이트
- 배포 완료 시 외부 시스템에서 후속 작업(테스트 스크립트 실행, 리포트 생성 등) 자동 트리거
- 내부 워크플로우와 연동하여 추가 검증·릴리스 작업 수행

3. Q: 사전 준비사항은 무엇인가요?
A:
1) CircleCI 프로젝트에 대한 Admin 권한 또는 Write 권한
2) 웹훅을 수신할 수 있는 유효한 HTTPS 엔드포인트(URL)
3) (선택) 인증·서명을 위한 시크릿 토큰
4) 외부 시스템에서 JSON 페이로드 파싱·처리 로직

4. Q: CircleCI 대시보드에서 웹훅을 추가하는 절차는?
A:
1) CircleCI 웹 콘솔에 로그인
2) 좌측 메뉴에서 해당 프로젝트 선택
3) 상단의 “Project Settings”(프로젝트 설정) 클릭
4) 왼쪽 메뉴 중 “Webhooks” 섹션 선택
5) “Add Webhook” 버튼 클릭
6) 웹훅 이름 입력(예: “Slack Notify”)
7) Payload URL 입력(예: https://example.com/webhook)
8) 이벤트 종류 선택
- job-completed, workflow-completed, job-started 등
9) (선택) 시크릿 토큰 입력 → CircleCI가 HMAC-SHA256 방식으로 페이로드에 서명
10) “Save Webhook” 클릭하여 저장

5. Q: 페이로드(Payload) 구조 예시는 어떻게 되나요?
A:
요청 헤더
- X-CircleCI-Signature: HMAC-SHA256 서명 값
- Content-Type: application/json
본문 예시
{
"pipeline": { "id": "...", "number": 123, … },
"workflow": { "id": "...", "name": "build-and-test", "status": "success", … },
"project": { "slug": "github/org/repo", … }, "trigger": { "type": "push", "actor": "username" },
"actions": [
{ "job_number": 456, "job_name": "test", "status": "failed", … }
]
}

6. Q: 어떤 이벤트를 구독할 수 있나요?
A:
- pipeline-created / pipeline-completed
- workflow-job / workflow-completed
- job-queued / job-started / job-completed
- schedule-triggered
필요에 따라 단일 이벤트 혹은 복수 이벤트를 선택해 페이로드를 받을 수 있습니다.

7. Q: 보안을 위한 서명 검증 방법은?
A:
1) 프로젝트 설정에서 입력한 “Signing Secret”(시크릿 토큰) 확보
2) 수신 서버에서 HTTP 헤더 X-CircleCI-Signature 값을 읽음
3) 전달받은 페이로드(raw body)와 시크릿 토큰으로 HMAC-SHA256 해시 생성
4) 생성된 해시와 헤더 값을 안전하게 비교(타이밍 어택 방지)
5) 일치할 경우 유효 요청으로 간주

8. Q: 웹훅 테스트·디버깅은 어떻게 하나요?
A:
- “Test Webhook” 버튼 사용: 수신 URL로 샘플 페이로드 전송
- Postman, curl 등 외부 툴로 수동 테스트
curl -X POST -H "Content-Type: application/json" -d '{…}' https://your.endpoint
- CircleCI 로그 확인: 대시보드 → Webhooks → 전송 내역(status 코드, 응답 시간)
- 수신 서버 로그: 웹훅 요청 도착 여부, 응답 코드(200 OK 등) 확인

9. Q: 자주 발생하는 문제와 해결책은?
A:
- 404 Not Found → URL 오타/라우팅 설정 확인
- 401/403 에러 → 시크릿 토큰 검증 로직 혹은 권한 설정 점검
- 타임아웃(504 Gateway Timeout) → 엔드포인트 처리 속도 개선, 리트라이 로직 추가
- 잘못된 페이로드 형식 → Content-Type 헤더, JSON 직렬화 방식 점검

10. Q: 웹훅을 삭제하거나 수정하려면?
A:
1) 프로젝트 설정 → Webhooks 메뉴 진입
2) 목록에서 대상 웹훅 우측의 Edit/Delete 버튼 클릭
3) 수정 사항 적용 후 Save, 또는 Delete로 완전 삭제

위 FAQ를 참고하여 CircleCI 웹훅을 안정적으로 설정·운영하시기 바랍니다.

서클CI(CircleCI)에서 웹후크(Webhook)를 설정하는 방법에 대해 설명하겠습니다.

웹후크는 특정 이벤트가 발생했을 때 지정된 URL로 HTTP POST 요청을 보내는 기능으로, CI/CD 프로세스에서 유용하게 사용됩니다.

서클CI에 웹후크 설정하는 방법 1. 프로젝트 선택 - 서클CI에 로그인한 후, 웹후크를 설정하고 싶은 프로젝트를 선택합니다.



2. 프로젝트 설정으로 이동 - 선택한 프로젝트의 대시보드에서 ‘Project Settings’(프로젝트 설정) 아이콘을 클릭합니다.



3. 웹후크 설정 - 프로젝트 설정 페이지에서 ‘Webhooks’(웹후크) 섹션으로 이동합니다.

여기서 새로운 웹후크를 추가할 수 있습니다.



4. 웹후크 추가 - ‘Add Webhook’(웹후크 추가) 버튼을 클릭합니다.

- 웹후크 URL 필드에 요청을 보낼 엔드포인트 URL을 입력합니다.



5. 이벤트 선택 - 웹후크를 발송할 이벤트를 선택합니다.

이를 통해 특정 푸시 이벤트, 빌드 성공, 빌드 실패 등의 상황에 따라 요청을 받을 수 있습니다.

- 선택할 수 있는 이벤트에는 다음과 같은 것들이 있습니다: - 빌드 성공 - 빌드 실패 - 테스트 성공 - 테스트 실패 등

6. 설정 저장 - 설정을 완료한 후, 'Save' 또는 'Add Webhook' 버튼을 클릭하여 변경 사항을 저장합니다.



7. 웹후크 테스트 (Optional) - 웹후크가 올바르게 작동하는지 확인하기 위해 테스트 요청을 보낼 수 있습니다.

이를 위해 설정된 웹후크 리스트에서 해당 웹후크 옆에 있는 테스트 버튼을 클릭하십시오.

8. 로그 및 디버깅 - 설정된 웹후크의 로그를 확인하여 요청이 제대로 전송되었는지, 서버에서 올바르게 처리되었는지를 확인할 수 있습니다.

이 정보는 문제 해결에 유용합니다.

유의사항 - URL이 올바르게 설정되었는지, 대기하고 있는 서버가 요청을 수신할 수 있는지 확인합니다.

- 인증이 필요한 웹후크의 경우 헤더를 추가해야 하는 경우도 있습니다.

그 또한 환경 변수로 설정할 수 있습니다.

- CORS 정책이나 방화벽 설정 등을 통해 웹후크가 정상적으로 작동하는지 확인해야 합니다.

위의 단계를 따라 서클CI에서 웹후크를 설정할 수 있습니다.

이를 통해 자동화된 빌드 프로세스나 커뮤니케이션을 더욱 원활하게 만들 수 있습니다.