웹훅

Tier: 무료, Premium, Ultimate
Offering: GitLab.com, Self-managed, GitLab Dedicated

웹훅(Webhooks)은 사용자가 정의하는 사용자 지정 HTTP 콜백입니다. 이들은 일반적으로 코드를 리포지터리로 푸시하거나 이슈에 댓글을 게시하는 등의 이벤트에 의해 트리거됩니다. 이벤트가 발생하면 소스 앱은 웹훅에 구성된 URI로 HTTP 요청을 생성합니다. 취해야 할 조치는 무엇이든 될 수 있습니다. 예를 들면 웹훅을 사용하여:

지속적 통합(CI) 작업을 트리거하거나 외부 이슈 트래커를 업데이트하거나 백업 미러를 업데이트하거나 프로덕션 서버에 배포할 수 있습니다.
작업이 실패할 때마다 Slack으로 알림을 보낼 수 있습니다.
GitLab에서 특정 프로젝트나 그룹에 대해 이슈가 생성될 때마다 Twilio를 사용하여 SMS로 알림을 받을 수 있습니다.
Merge Request에 자동으로 레이블을 할당할 수 있습니다.

이벤트가 발생할 때 GitLab 프로젝트나 그룹(group)을 구성하여 퍼센트 인코딩된 웹훅 URL을 트리거할 수 있습니다. 예를 들어, 새 코드가 푸시되거나 새로운 이슈가 생성될 때입니다. 웹훅은 특정 이벤트를 수신하고 GitLab은 데이터와 함께 웹훅 URL로 POST 요청을 보냅니다.

일반적으로 귀하의 요구 사항에 따라 GitLab에서 정보를 수신하고 다른 앱으로 전송하는 웹훅 리시버(webhook receiver)를 설정합니다. 프로젝트마다 Slack으로 알림을 보내는 내장 리시버를 사용할 수 있습니다.

GitLab.com은 프로젝트 및 그룹 당 웹훅 및 웹훅의 크기의 최대 개수뿐만 아니라 분당 웹훅 호출 수 등 웹훅 한도를 적용합니다.

그룹 웹훅

Tier: Premium, Ultimate
Offering: GitLab.com, Self-managed, GitLab Dedicated

그룹 웹훅은 그룹 및 해당 하위 그룹의 모든 프로젝트에서 발생하는 이벤트에 의해 트리거되는 그룹과 프로젝트에서 동일한 웹훅을 구성할 경우 동일한 이벤트에 의해 두 곳에서 모두 트리거됩니다.

그룹 웹훅은 또한 다음과 같이 그룹에 특정한 이벤트를 수신하도록 구성될 수 있습니다:

GitLab에서 웹훅 구성

프로젝트 또는 그룹에서 웹훅을 구성하려면 다음을 수행합니다:

프로젝트 또는 그룹에서 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
새 웹훅 추가를 선택합니다.
URL에 웹훅 엔드포인트의 URL을 입력합니다. URL에 하나 이상의 특수 문자가 포함된 경우 URL은 퍼센트 인코딩되어야 합니다.
Secret token에 페이로드를 유효성 검사하기 위한 비밀 토큰을 입력합니다.
트리거 섹션에서 웹훅을 트리거할 이벤트를 선택합니다.
선택 사항입니다. SSL 검증 비활성화를 위해 SSL 검증 활성화 확인란을 선택 해제합니다.
웹훅 추가를 선택합니다.

웹훅 URL의 민감한 부분 가리기

인터페이스 배포 시 GitLab 15.5에서 webhook_form_mask_url이라는 플래그로 도입됨. 기본적으로 비활성화됨.
GitLab 15.6에서 GitLab.com에 적용됨.
GitLab 15.7에서 일반적으로 사용 가능. webhook_form_mask_url 피처 플래그가 제거됨.

웹훅 URL의 민감한 부분을 정의하고 마스킹된 값으로 치환하여 웹훅이 실행될 때마다 여러 번 수행할 수 있습니다. 민감한 부분은 기록되지 않으며 데이터베이스에 저장될 때 암호화됩니다.

웹훅의 민감한 부분을 마스킹하려면 다음을 수행합니다:

프로젝트 또는 그룹에서 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
URL에 전체 웹훅 URL을 입력합니다.
URL 일부 가리기를 선택합니다.
URL 일부 가릴 구간에 가리고자 하는 부분을 입력합니다.
UI에서의 모습에 마스킹 값을 입력합니다.

각 웹훅에 민감한 부분을 보간하려면 url_variables을 사용합니다. 예를 들어, 웹훅의 URL이 다음과 같은 경우:

https://{subdomain}.example.com/{path}?key={value}

다음과 같은 변수를 정의해야 합니다:

subdomain
path
value

변수의 이름은 소문자 알파벳(a-z), 숫자(0-9), 또는 밑줄(_)만 포함할 수 있습니다. URL 변수는 REST API를 사용하여 직접 정의할 수 있습니다.

사용자 정의 웹훅 템플릿

인터페이스 배포 시 GitLab 16.10에서 custom_webhook_template이라는 플래그로 도입됨. 기본적으로 활성화됨.

플래그: Self-managed GitLab에서는 기본적으로 이 기능을 사용할 수 있습니다. 특성을 숨기려면 관리자가 custom_webhook_template라는 플래그를 비활성화할 수 있습니다. GitLab.com 및 GitLab Dedicated에서는 이 기능을 사용할 수 있습니다.

웹훅 구성에서 사용자 정의 페이로드 템플릿을 설정할 수 있습니다. 요청 본문은 현재 이벤트에 대한 데이터로부터 템플릿에서 렌더링됩니다. 템플릿은 유효한 JSON으로 렌더링해야 합니다.

원하는 이벤트의 페이로드에서의 모든 필드를 사용할 수 있습니다. 예를 들어 작업 이벤트의 경우 {{build_name}}, 배포 이벤트의 경우 {{deployable_url}} 등이 있습니다. 객체 안에 중첩된 속성에 액세스하려면 .로 구분된 경로 세그먼트를 지정합니다. 예를 들어:

다음과 같은 사용자 정의 페이로드 템플릿이 있다면:

{
  "event": "{{object_kind}}",
  "project_name": "{{project.name}}"
}

다음과 같은 push 이벤트와 결합된 요청 페이로드가 생성됩니다:

{
  "event": "push",
  "project_name": "Example"
}

웹훅 수신기 엔드포인트 구성

웹훅 수신기 엔드포인트는 빠르고 안정적이어야 합니다. 느립니다. 불안정한 수신기는 시스템 신뢰성을 보장하기 위해 자동으로 비활성화될 수 있습니다. 실패한 웹훅은 중복 이벤트를 유발할 수 있습니다.

엔드포인트는 다음과 같은 모범 사례를 따라야 합니다:

200 또는 201 상태 응답으로 빠르게 응답하세요. 동일한 요청에서 웹훅을 처리하는 중요한 처리를 피하십시오. 대신, 받은 후 웹훅을 처리하기 위한 대기열을 구현하십시오. 타임아웃 제한 이전에 응답하지 않는 웹훅 수신기는 GitLab.com에서 자동으로 비활성화될 수 있습니다.
중복 이벤트를 처리할 준비를 하세요. 일부 상황에서, 동일한 이벤트가 두 번 전송될 수 있습니다. 이 문제를 완화하려면 엔드포인트가 신뢰할 수 있고 빠르며 안정적인지 확인하세요.
응답 헤더와 본문을 최소화하세요. GitLab은 응답 헤더나 본문을 검토하지 않습니다. GitLab은 이것들을 저장하여 문제를 진단하는 데 나중에 사용할 수 있도록 합니다. 반환된 헤더의 수와 크기를 제한해야 합니다. 또한 웹훅 요청에 빈 본문으로 응답할 수 있습니다.
클라이언트 오류 상태 응답만 반환하십시오(4xx 범위 내) 웹훅이 잘못 구성되었음을 나타내기 위해. 이 범위의 응답은 웹훅이 자동으로 비활성화될 수 있습니다. 예를 들어, 수신기가 푸시 이벤트만 지원하는 경우, 잘못된 구성의 표시로 400를 반환하거나 잘못된 이벤트 페이로드를 무시할 수 있습니다.
이벤트가 처리되었을 경우에는 500 서버 오류 상태 응답을 반환하지 마십시오. 이러한 응답은 웹훅이 자동으로 비활성화될 수 있습니다.
유효하지 않은 HTTP 응답은 실패한 요청으로 처리됩니다.

웹훅 타임아웃 제한

GitLab.com의 웹훅 타임아웃 제한은 10초입니다. GitLab Self-managed에서는 관리자가 웹훅 타임아웃 제한을 변경할 수 있습니다.

자동으로 비활성화된 웹훅

GitLab 13.12에서 프로젝트 웹훅을 위해 도입되었으며, 기본적으로 web_hooks_disable_failed이름의 플래그로 비활성화됩니다.
GitLab 15.7에서 프로젝트 웹훅을 위해 일반적으로 사용 가능하게 됨. 피처 플래그 web_hooks_disable_failed가 제거되었습니다.
GitLab 15.10에서 그룹 웹훅을 위해 도입되었습니다.
GitLab 15.10에서 자체 호스팅된 GitLab에서는 기본적으로 auto_disabling_web_hooks이름의 플래그로 비활성화됩니다.

플래그: 자체 호스팅된 GitLab에서는 기본적으로 이 기능을 사용할 수 없습니다. 사용하려면 관리자가 auto_disabling_web_hooks이름의 피처 플래그를 활성화해야 합니다. GitLab.com에서 이 기능을 사용할 수 있습니다. GitLab의 전용 서비스에서는 이 기능을 사용할 수 없습니다.

연속해서 네 번 실패한 프로젝트 또는 그룹 웹훅은 자동으로 비활성화됩니다.

5xx 범위의 응답 코드를 반환하거나 타임아웃이나 기타 HTTP 오류를 경험한 프로젝트 또는 그룹 웹훅은 간헐적으로 실패했다고 간주되며 일시적으로 비활성화됩니다. 이러한 웹훅은 초기에는 1분 동안 비활성화되며, 각 후속 실패마다 최대 24시간까지 연장됩니다.

4xx 범위의 응답 코드를 반환하는 프로젝트 또는 그룹 웹훅은 잘못 구성되었다고 간주되며 매뉴얼으로 다시 활성화할 때까지 영구적으로 비활성화됩니다.

비활성화된 웹훅 다시 활성화

GitLab 15.2에서 도입되었으며, 기본적으로 webhooks_failed_callout이름의 플래그로 비활성화됩니다.
GitLab 15.7에서 프로젝트 웹훅을 위해 일반적으로 사용 가능하게 됨. 피처 플래그 webhooks_failed_callout가 제거되었습니다.

웹훅이 실패하는 경우, 편집 페이지 상단에 실패한 웹훅이 왜 비활성화되었는지 및 자동으로 다시 활성화되는 시기에 대한 배너가 표시됩니다. 예를 들어:

실패한 웹훅의 경우, 오류 배너가 표시됩니다:

실패하거나 실패한 웹훅을 다시 활성화하려면 테스트 요청을 보내세요. 테스트 요청이 성공하면 웹훅이 다시 활성화됩니다.

웹훅 테스트

웹훅을 수동으로 트리거하여 정상 작동하는지 확인할 수 있습니다. 비활성화된 웹훅을 다시 활성화하려면 테스트 요청을 보낼 수도 있습니다.

예를 들어, push events를 테스트하려면 프로젝트에 적어도 하나의 커밋이 있어야 합니다. 웹훅은 이 커밋을 사용합니다.

프로젝트 및 그룹 웹훅의 일부 이벤트에 대해 테스트가 지원되지 않습니다. 자세한 내용은 이슈 379201을 참조하십시오.

전제 조건:

프로젝트 웹훅을 테스트하려면 프로젝트의 유지자 역할 이상이어야 합니다.
그룹 웹훅을 테스트하려면 그룹의 소유자 역할이어야 합니다.

웹훅을 테스트하려면:

프로젝트나 그룹에서 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
구성된 웹훅 디렉터리으로 스크롤합니다.
테스트 드롭다운 디렉터리에서 테스트할 이벤트 유형을 선택하세요.

또한 편집 페이지에서 웹훅을 테스트할 수 있습니다.

예제 웹훅 수신기 생성하기

GitLab 웹훅이 어떻게 작동하는지 테스트하려면 콘솔 세션에서 실행 중인 echo 스크립트를 사용할 수 있습니다. 다음 스크립트가 작동하려면 Ruby가 설치되어 있어야 합니다.

다음 파일을 print_http_body.rb로 저장하세요.

require 'webrick'
   
server = WEBrick::HTTPServer.new(:Port => ARGV.first)
server.mount_proc '/' do |req, res|
  puts req.body
end
   
trap 'INT' do
  server.shutdown
end
server.start

사용되지 않는 포트를 선택하십시오 (예: 8000) 그리고 스크립트를 시작하세요.
```
ruby print_http_body.rb 8000
```
GitLab에서 웹훅을 구성하고 수신기 URL을 추가하세요. 예를 들어 http://receiver.example.com:8000/.

Test를 선택하세요. 콘솔에서 다음과 같은 내용을 볼 수 있어야 합니다.

{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}
example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0
- -> /

이 수신기를 추가하려면 로컬 네트워크에 대한 요청을 허용해야 할 수 있습니다.

비밀 토큰 사용하여 페이로드 유효성 검사하기

수신된 페이로드를 유효성 검사하기 위해 비밀 토큰을 지정할 수 있습니다. 해당 토큰은 X-Gitlab-Token HTTP 헤더로 후크 요청과 함께 전송됩니다. 웹훅 엔드포인트는 해당 토큰을 확인하여 요청이 적절한지를 검증할 수 있습니다.

브랜치로 푸시 이벤트 필터링하기

브랜치별로 푸시 이벤트를 필터링할 수 있습니다. 웹훅 엔드포인트로 보내지는 푸시 이벤트를 필터링하는 다음 옵션 중 하나를 사용하세요:

모든 브랜치: 모든 브랜치의 푸시 이벤트.
와일드카드 패턴: 와일드카드 패턴과 일치하는 브랜치의 푸시 이벤트(예: *-stable 또는 production/*).
정규 표현식: 정규 표현식 (regex)와 일치하는 브랜치의 푸시 이벤트. 정규식 패턴은 RE2 구문을 따라야 합니다. 예를 들어, main을 제외하려면 다음과 같이 사용할 수 있습니다:
```
\b(?:m(?!ain\b)|ma(?!in\b)|mai(?!n\b)|[a-l]|[n-z])\w*|\b\w{1,3}\b|\W+
```

프로젝트나 그룹에 대한 브랜치 필터링을 구성하려면 GitLab에서 웹훅을 구성하세요.

웹훅 본문에 표시되는 이미지 URL

상대적 이미지 참조는 웹훅 본문에서 절대 URL을 사용하도록 다시 작성됩니다. 예를 들어, 이미지, Merge Request, 코멘트 또는 위키 페이지에 다음 이미지 참조가 포함되어 있다면,

![image](/uploads/$sha/image.png)

만약:

GitLab이 gitlab.example.com에 설치되어 있다면.
프로젝트가 example-group/example-project에 있다면.

참조는 웹훅 본문에서 다음과 같이 다시 작성됩니다.

![image](https://gitlab.example.com/example-group/example-project/uploads/$sha/image.png)

이미지 URL은 다음과 같은 경우에는 다시 작성되지 않습니다:

이미 HTTP, HTTPS 또는 프로토콜 상대적 URL을 가리키고 있는 경우.
링크 레이블과 같은 고급 마크다운 기능을 사용하고 있는 경우.

이벤트

웹훅에 대한 지원되는 이벤트에 대한 자세한 정보는 웹훅 이벤트를 참조하세요.

전달 헤더

X-Gitlab-Event-UUID 헤더는 GitLab 14.8에서 도입되었습니다.
X-Gitlab-Instance 헤더는 GitLab 15.5에서 도입되었습니다.
X-Gitlab-Webhook-UUID 헤더는 GitLab 16.2에서 도입되었습니다.

엔드포인트로의 웹훅 요청은 다음 헤더를 포함합니다:

헤더	설명	예시
`User-Agent`	`"Gitlab/<VERSION>"` 형식의 사용자 에이전트입니다.	`"GitLab/15.5.0-pre"`
`X-Gitlab-Instance`	웹훅을 보낸 GitLab 인스턴스의 호스트 이름입니다.	`"https://gitlab.com"`
`X-Gitlab-Webhook-UUID`	웹훅 당 고유 ID입니다.	`"02affd2d-2cba-4033-917d-ec22d5dc4b38"`
`X-Gitlab-Event`	웹훅 유형의 이름입니다. 이벤트 유형에 해당하지만 `"<EVENT> Hook"` 형식으로 표시됩니다.	`"Push Hook"`
`X-Gitlab-Event-UUID`	재귀적이지 않은 웹훅 당 고유 ID입니다. 웹훅이 이전 웹훅에 의해 트리거된 경우 재귀적입니다. 재귀적 웹훅은 이 헤더에 대해 동일한 값이 있습니다.	`"13792a34-cac6-4fda-95a8-c58e00a3954e"`

웹훅 개발

웹훅 설정에 대한 기존 HTTPS 엔드포인트나 URL이 없다면, 서버에 배포해야 합니다. 이 HTTPS 엔드포인트는 구성에서 사용됩니다. GitLab 웹훅에 대한 개발 및 페이로드 캡처를 위해 다음을 사용할 수 있습니다:

공개 웹훅 검사 및 테스트 도구
GitLab 개발 키트 (GDK)
GitLab 설정의 최근에 트리거된 웹훅 페이로드

공개 웹훅 검사 및 테스트 도구

공용 도구를 사용하여 웹훅 페이로드를 검사하고 테스트할 수 있습니다. 이러한 도구는 HTTP 요청에 대한 캐치-올 엔드포인트로 작용하고 200 OK HTTP 상태 코드로 응답합니다. 이러한 페이로드를 사용하여 웹훅 서비스를 개발할 수 있습니다.

이러한 도구를 사용할 때에는 외부 도구로 민감한 데이터를 보낼 수 있기 때문에 주의해야 합니다. 이러한 도구와 함께 테스트 토큰을 사용하고 무심코 외부로 보내진 보안 정보를 교체해야 합니다.

이러한 공용 도구로는 다음이 있습니다:

Beeceptor: 임시 HTTPS 엔드포인트를 생성하고 들어오는 페이로드를 검사합니다.
Webhook.site: 들어오는 페이로드를 검토합니다.
Webhook Tester: 들어오는 페이로드를 검사하고 디버그할 수 있습니다.

GitLab 개발 키트 (GDK)

보다 안전한 개발 환경을 위해 GitLab Development Kit (GDK)을 사용하여 로컬에서 GitLab 웹훅을 개발할 수 있습니다. GDK를 사용하면 로컬 GitLab 인스턴스에서 웹훅을 로컬 머신에서 실행 중인 웹훅 수신기로 보낼 수 있습니다. 이 접근 방식을 사용하려면 GDK를 설치하고 구성해야 합니다.

최근에 GitLab 설정에서 트리거된 웹훅 페이로드

GitLab 설정에서 최근에 트리거된 웹훅 페이로드를 검토할 수 있습니다. 각 웹훅 이벤트에는 GitLab이 웹훅 엔드포인트로부터 보내고 받는 데이터에 대한 정보가 있는 상세 페이지가 있습니다.

상호 TLS를 지원하도록 웹훅 구성

Offering: Self-managed, GitLab Dedicated

GitLab 16.9에서 도입되었습니다.

필수 조건:

GitLab 관리자여야 합니다.

상호 TLS를 지원하도록 웹훅을 구성하려면 PEM 형식의 클라이언트 인증서를 구성해야 합니다. 이 인증서는 전역적으로 설정되며 TLS 핸드셰이크 중 서버에 제시됩니다. 인증서는 PEM 암호구문으로 보호할 수도 있습니다.

인증서를 구성하려면 아래 지침을 따르세요.

/etc/gitlab/gitlab.rb 파일을 편집하세요:

gitlab_rails['http_client']['tls_client_cert_file'] = '<클라이언트 PEM 파일 경로>'
gitlab_rails['http_client']['tls_client_cert_password'] = '<선택적 암호>'

파일을 저장하고 GitLab을 다시 구성하세요:
```
sudo gitlab-ctl reconfigure
```

문제 해결

GitLab 15.3에서 도입됨.

GitLab은 각 웹훅 요청의 이력을 기록합니다. 문제 해결 테이블에서 2일 이내에 수행된 요청을 볼 수 있습니다.

필수 조건:

프로젝트 웹훅의 문제를 해결하려면 프로젝트의 관리자 역할을 가져야 합니다.
그룹 웹훅의 문제를 해결하려면 그룹에 대한 소유자 역할을 가져야 합니다.

테이블을 보려면:

프로젝트 또는 그룹에서 왼쪽 사이드바에서 Settings > Webhooks를 선택하세요.
아래로 스크롤하여 웹훅을 선택하세요.
각 자동으로 비활성화된 웹훅에는 다음이 나열된 배지가 있습니다:
- 매뉴얼으로 다시 사용해야 하는 경우 연결 실패
- 임시로 비활성화되었다가 타임아웃이 종료되면 자동으로 다시 활성화되는 경우 연결 실패
보고 싶은 웹훅에 대해 수정을 선택하세요.

테이블에는 각 요청에 대한 다음과 같은 세부 정보가 포함됩니다:

HTTP 상태 코드 (200-299 코드에는 녹색, 다른 코드에는 빨간색 및 전송 실패 시 내부 오류)
트리거된 이벤트
요청의 경과 시간
요청이 수행된 상대 시간

각 웹훅 이벤트에는 해당 세부 정보 페이지가 있습니다. 이 페이지에는 GitLab이 보낸 데이터(요청 헤더 및 본문) 및 받은 데이터(응답 헤더 및 본문)에 대한 정보가 포함되어 있습니다. 세부 정보 페이지를 보려면 해당 웹훅 이벤트에 대해 세부 정보 보기를 선택하세요.

동일한 데이터로 전송을 반복하려면 요청 다시 보내기를 선택하세요.

웹훅의 URL 또는 비밀 토큰을 업데이트하면 데이터가 새 주소로 전달됩니다.

지역 발급자 인증서 가져오기 불가능

SSL 검증이 활성화된 경우, GitLab이 웹훅 엔드포인트의 SSL 인증서를 확인할 수 없는 오류가 발생할 수 있습니다. 이러한 오류가 발생하는 typicall 한 경우는 루트 인증서가 CAcert.org에 의해 신뢰할 수 있는 인증 기관에 의해 발급되지 않았기 때문입니다.

그렇지 않은 경우 SSL Checker를 사용하여 결함을 식별할 수 있습니다. 누락된 중간 인증서는 확인 실패의 흔한 원인입니다.

웹훅 실패 또는 여러 웹훅 요청이 트리거됨

여러 웹훅 요청을 받는 경우, 웹훅이 타임 아웃된 것일 수 있습니다.

웹훅이 트리거되지 않음

GitLab 16.3**에서 Silent Mode에 대한 웹훅이 트리거되지 않습니다.

웹훅이 트리거되지 않을 때, 다음을 확인하세요:

웹훅이 자동으로 비활성화되지 않았는지 확인하십시오.
GitLab 인스턴스가 Silent Mode에서 실행 중이 아닌지 확인하십시오.

On this page

웹훅

그룹 웹훅

GitLab에서 웹훅 구성

웹훅 URL의 민감한 부분 가리기

사용자 정의 웹훅 템플릿

웹훅 수신기 엔드포인트 구성

웹훅 타임아웃 제한

자동으로 비활성화된 웹훅

비활성화된 웹훅 다시 활성화

웹훅 테스트

예제 웹훅 수신기 생성하기

비밀 토큰 사용하여 페이로드 유효성 검사하기

브랜치로 푸시 이벤트 필터링하기

웹훅 본문에 표시되는 이미지 URL

이벤트

전달 헤더

웹훅 개발

공개 웹훅 검사 및 테스트 도구

GitLab 개발 키트 (GDK)

최근에 GitLab 설정에서 트리거된 웹훅 페이로드

상호 TLS를 지원하도록 웹훅 구성

관련 주제

문제 해결

지역 발급자 인증서 가져오기 불가능

웹훅 실패 또는 여러 웹훅 요청이 트리거됨

웹훅이 트리거되지 않음

도움말

기능 사용 가능성과 제품 평가판

도움받기

On this page