웹훅은 실시간 알림을 통해 GitLab을 다른 도구 및 시스템에 연결합니다. GitLab에서 중요한 이벤트가 발생하면 웹훅이 해당 정보를 외부 애플리케이션으로 직접 보냅니다. 머지 요청, 코드 푸시 및 이슈 업데이트에 반응하여 자동화 워크플로우를 구축하세요.

웹훅을 사용하면 변경이 발생할 때 팀이 동기화 상태를 유지합니다:

• GitLab 이슈가 변경되면 외부 이슈 트래커가 자동으로 업데이트됩니다.
• 채팅 애플리케이션이 파이프라인 완료에 대해 팀원에게 알립니다.
• 코드가 메인 브랜치에 도달하면 커스텀 스크립트가 애플리케이션을 배포합니다.
• 모니터링 시스템이 전체 조직의 개발 활동을 추적합니다.

웹훅 이벤트#

GitLab의 다양한 이벤트가 웹훅을 트리거할 수 있습니다. 예를 들어:

• 저장소에 코드를 푸시합니다.
• 이슈에 댓글을 게시합니다.
• 머지 요청을 생성합니다.

웹훅 한도#

GitLab.com은 다음을 포함한 웹훅 한도를 적용합니다:

• 프로젝트 또는 그룹당 최대 웹훅 수.
• 분당 웹훅 호출 수.
• 웹훅 타임아웃 기간.

GitLab Self-Managed의 경우 관리자가 이러한 한도를 수정할 수 있습니다.

푸시 이벤트 한도#

GitLab은 여러 변경 사항을 포함하는 푸시 이벤트에 대한 웹훅 트리거를 제한합니다:

• 기본 한도: 푸시당 브랜치 또는 태그 3개.
• 초과 시 동작: 전체 푸시 이벤트에 대해 웹훅이 트리거되지 않습니다.
• 적용 대상: 프로젝트 웹훅 및 시스템 훅 모두.
• 구성: GitLab Self-Managed 관리자는 애플리케이션 설정 API를 통해 push_event_hooks_limit 설정을 수정할 수 있습니다.

여러 태그나 브랜치를 동시에 자주 푸시하고 웹훅 알림이 필요한 경우, 이 한도를 늘리도록 GitLab 관리자에게 문의하세요.

그룹 웹훅#

그룹 웹훅은 그룹 및 하위 그룹의 모든 프로젝트에서 발생하는 이벤트에 대한 알림을 보내는 커스텀 HTTP 콜백입니다.

그룹 웹훅 이벤트 유형#

다음을 수신하도록 그룹 웹훅을 구성할 수 있습니다:

• 그룹 및 하위 그룹의 프로젝트에서 발생하는 모든 이벤트
• 그룹 구성원 이벤트, 프로젝트 이벤트, 하위 그룹 이벤트를 포함한 그룹별 이벤트

프로젝트와 그룹 모두의 웹훅#

그룹과 해당 그룹의 프로젝트 모두에 동일한 웹훅을 구성하면 해당 프로젝트의 이벤트에 대해 두 웹훅이 모두 트리거됩니다. 이를 통해 GitLab 조직의 다양한 수준에서 유연한 이벤트 처리가 가능합니다.

웹훅 구성#

GitLab에서 웹훅을 생성하고 구성하여 프로젝트의 워크플로우와 통합합니다. 이러한 기능을 사용하여 특정 요구 사항을 충족하는 웹훅을 설정합니다.

웹훅 만들기#

히스토리

• 이름 및 설명이 GitLab 16.9에 도입되었습니다.
• 서명 토큰 텍스트 상자가 GitLab 19.0에 webhook_signing_token이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화됩니다.

새 웹훅의 경우 시크릿 토큰 대신 서명 토큰을 사용합니다. 서명 토큰은 페이로드에 대해 HMAC-SHA256 서명을 계산하므로 엔드포인트가 요청의 진위성과 무결성을 모두 확인할 수 있습니다. 시크릿 토큰은 헤더에 일반 텍스트 값만 제공하므로 보안 보장이 약합니다. 새 웹훅에는 시크릿 토큰을 권장하지 않습니다.

프로젝트나 그룹의 이벤트에 대한 알림을 보내는 웹훅을 만듭니다.

사전 요구 사항:

• 프로젝트 웹훅의 경우 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.
• 그룹 웹훅의 경우 그룹에 대한 소유자 역할이 있어야 합니다.

웹훅을 만들려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
3. 새 웹훅 추가를 선택합니다.
4. URL에 웹훅 엔드포인트의 URL을 입력합니다. 특수 문자에는 퍼센트 인코딩을 사용합니다.
5. 선택 사항. 웹훅에 대한 이름과 설명을 입력합니다.
6. 선택 사항. 요청 인증을 구성합니다. 강화된 보안을 위해 서명 토큰을 사용합니다:
   • 서명 토큰 (권장): 서명 토큰 생성을 선택합니다. 토큰은 한 번만 표시되므로 지금 복사하여 저장하세요. 웹훅 엔드포인트는 이 토큰을 사용하여 HMAC-SHA256 서명을 확인할 수 있습니다.
   • 시크릿 토큰 (권장하지 않음): 시크릿 토큰 필드에 토큰을 입력합니다. 이 토큰은 X-Gitlab-Token HTTP 헤더에 일반 텍스트로 전송되며 서명 토큰보다 보안 보장이 약합니다. 새 웹훅에는 서명 토큰을 대신 사용하세요.
7. 트리거 섹션에서 웹훅을 트리거할 이벤트를 선택합니다.
8. 선택 사항. SSL 검증을 비활성화하려면 SSL 검증 활성화 체크박스를 지웁니다.
9. 웹훅 추가를 선택합니다.

서명 토큰#

히스토리

• GitLab 19.0에 webhook_signing_token이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화됩니다.

서명 토큰을 사용하여 웹훅 페이로드가 GitLab에서 발생했으며 변조되지 않았음을 확인합니다. 시크릿 토큰과 달리 서명 토큰은 페이로드에 대해 HMAC-SHA256 서명을 계산하는 데 사용됩니다. 따라서 수신자는 수신된 페이로드의 진위성과 무결성을 독립적으로 확인할 수 있습니다.

GitLab 웹훅 전달은 Standard Webhooks 사양을 따릅니다. 모든 웹훅 요청에는 webhook-id 및 webhook-timestamp 헤더가 포함됩니다. 서명 토큰이 구성된 경우 GitLab은 HMAC-SHA256 서명과 함께 webhook-signature 헤더도 포함합니다. 각 서명의 형식은 v1,{base64_signature}입니다. 헤더에는 공백으로 구분된 여러 서명이 포함될 수 있습니다. GitLab은 현재 하나의 서명을 보내지만 이는 변경될 수 있습니다. 서명은 {message_id}.{timestamp}.{body} 문자열에 대해 계산됩니다. 여기서:

• {message_id}는 webhook-id 헤더의 값입니다.
• {timestamp}는 webhook-timestamp 헤더의 값입니다.
• {body}는 원시 JSON 요청 본문입니다.

서명 확인#

웹훅 엔드포인트에서 서명을 확인하려면:

1. webhook-id, webhook-timestamp, webhook-signature 헤더 값을 가져옵니다.
2. 공백으로 webhook-signature 값을 분할하여 서명 목록을 가져옵니다.
3. 메시지 문자열을 구성합니다: "{message_id}.{timestamp}.{body}".
4. 서명 토큰을 디코딩합니다: whsec_ 접두사를 제거한 다음 나머지를 base64 디코딩합니다.
5. 디코딩된 키를 사용하여 HMAC-SHA256 다이제스트를 계산합니다.
6. 다이제스트를 base64로 인코딩하고 v1,을 접두사로 붙입니다.
7. 계산된 서명이 서명 목록의 항목과 일치하는지 확인합니다. 타이밍 공격을 방지하려면 상수 시간 비교를 사용합니다.

Ruby 예시:

require 'base64'
require 'openssl'

def valid_signature?(signing_token, message_id, timestamp, body, received_signatures)
  raw_key = Base64.strict_decode64(signing_token.delete_prefix('whsec_'))
  message = "#{message_id}.#{timestamp}.#{body}"
  digest = OpenSSL::HMAC.digest('sha256', raw_key, message)
  expected = "v1,#{Base64.strict_encode64(digest)}"
  received_signatures.split(' ').any? do |sig|
    ActiveSupport::SecurityUtils.secure_compare(expected, sig)
  end
end

Python 예시:

import base64
import hashlib
import hmac

def valid_signature(signing_token, message_id, timestamp, body, received_signatures):
    raw_key = base64.b64decode(signing_token.removeprefix('whsec_'))
    message = f"{message_id}.{timestamp}.{body}".encode('utf-8')
    digest = hmac.new(raw_key, message, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode('utf-8')
    return any(
        hmac.compare_digest(expected, sig)
        for sig in received_signatures.split(' ')
    )

이전 버전과의 호환성#

서명 토큰은 기존 시크릿 토큰과 함께 작동합니다. 동일한 웹훅에 두 가지를 모두 구성할 수 있습니다:

• 시크릿 토큰이 구성된 경우 X-Gitlab-Token 헤더가 계속 전송됩니다.
• 서명 토큰이 구성된 경우 webhook-signature 및 webhook-id 헤더가 전송됩니다.

다운타임 없이 시크릿 토큰을 사용하는 기존 웹훅을 서명 토큰으로 마이그레이션하려면, 전환 중에 동일한 웹훅에 두 토큰을 모두 구성하세요. webhook-signature가 있을 때 서명을 확인하고 그렇지 않으면 시크릿 토큰으로 폴백하도록 수신기를 업데이트하세요.

수신기가 서명을 올바르게 처리하면 웹훅 설정에서 시크릿 토큰을 제거할 수 있습니다.

보안 고려 사항#

재생 공격을 방지하려면 페이로드를 처리하기 전에 webhook-timestamp의 타임스탬프가 최근 것인지 확인합니다.

서명 토큰은 API에서 반환되지 않습니다.

웹훅 URL의 민감한 부분 마스킹#

보안 강화를 위해 웹훅 URL의 민감한 부분을 마스킹합니다. 마스킹된 부분은 웹훅이 실행될 때 구성된 값으로 교체되고, 로깅되지 않으며, 데이터베이스에서 암호화되어 저장됩니다.

웹훅 URL의 민감한 부분을 마스킹하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 웹훅을 선택합니다.
3. URL에 웹훅의 전체 URL을 입력합니다.
4. 마스킹할 부분을 정의하려면 URL 마스킹 추가를 선택합니다.
5. 마스킹할 URL 부분에 마스킹할 URL 부분을 입력합니다.
6. UI에서 표시되는 방식에 마스킹된 부분 대신 표시할 값을 입력합니다. 변수 이름에는 소문자(a-z), 숫자(0-9) 또는 밑줄(_)만 포함할 수 있습니다.
7. 변경 사항 저장을 선택합니다.

마스킹된 값은 UI에서 숨겨진 상태로 표시됩니다. 예를 들어, path와 value 변수를 정의하면 웹훅 URL은 다음과 같이 표시될 수 있습니다:

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

커스텀 헤더#

히스토리

• GitLab 16.11에서 custom_webhook_headers 플래그가 있는 상태로 도입되었습니다. 기본적으로 활성화됩니다.
• GitLab 17.0에서 일반 사용 가능. 기능 플래그 custom_webhook_headers 제거됨.

외부 서비스 인증을 위해 웹훅 요청에 커스텀 헤더를 추가합니다. 웹훅당 최대 20개의 커스텀 헤더를 구성할 수 있습니다.

커스텀 헤더 요구 사항:

• 전달 헤더의 값을 재정의하지 않아야 합니다.
• 영숫자 문자, 마침표, 대시 또는 밑줄만 포함해야 합니다.
• 문자로 시작하고 문자나 숫자로 끝나야 합니다.
• 연속된 마침표, 대시 또는 밑줄이 없어야 합니다.

커스텀 헤더는 마스킹된 값으로 최근 이벤트에 표시됩니다.

커스텀 웹훅 템플릿#

히스토리

• GitLab 16.10에서 custom_webhook_template 플래그가 있는 상태로 도입되었습니다. 기본적으로 활성화됩니다.
• GitLab 17.0에서 일반 사용 가능. 기능 플래그 custom_webhook_template 제거됨.
• GitLab 18.4에서 custom_webhook_template_serialization 플래그가 있는 상태로 도입된 보간 필드 값의 JSON 직렬화. 기본적으로 비활성화됩니다.
• GitLab 18.6에서 보간 필드 값의 JSON 직렬화가 일반 사용 가능으로 변경됨. 기능 플래그 custom_webhook_template_serialization 기본적으로 활성화됨.
• GitLab 18.10에서 기능 플래그 custom_webhook_template_serialization 제거.

웹훅의 커스텀 페이로드 템플릿을 만들어 요청 본문에서 보낼 데이터를 제어합니다.

커스텀 웹훅 템플릿 만들기#

• 프로젝트 웹훅의 경우 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.
• 그룹 웹훅의 경우 그룹에 대한 소유자 역할이 있어야 합니다.

커스텀 웹훅 템플릿을 만들려면:

1. 웹훅 구성으로 이동합니다.
2. 커스텀 웹훅 템플릿을 설정합니다.
3. 템플릿이 유효한 JSON으로 렌더링되는지 확인합니다.

템플릿에서 이벤트 페이로드의 필드를 사용합니다. 예를 들어:

• 작업 이벤트의 경우 {{build_name}}
• 배포 이벤트의 경우 {{deployable_url}}

중첩된 속성에 액세스하려면 마침표를 사용하여 경로 세그먼트를 구분합니다.

커스텀 웹훅 템플릿 예시#

다음 커스텀 페이로드 템플릿의 경우:

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

push 이벤트에 대한 결과 요청 페이로드는 다음과 같습니다:

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

커스텀 웹훅 템플릿은 배열의 속성에 액세스할 수 없습니다. 이 기능에 대한 지원은 이슈 463332에서 제안되었습니다.

브랜치별로 푸시 이벤트 필터링#

브랜치 이름으로 웹훅 엔드포인트로 보내는 push 이벤트를 필터링합니다. 다음 필터링 옵션 중 하나를 사용합니다:

• 모든 브랜치: 모든 브랜치에서 푸시 이벤트를 받습니다.
• 와일드카드 패턴: 와일드카드 패턴과 일치하는 브랜치에서 푸시 이벤트를 받습니다.
• 정규식: 정규식(regex)과 일치하는 브랜치에서 푸시 이벤트를 받습니다.

와일드카드 패턴 사용#

와일드카드 패턴으로 필터링하려면:

1. 웹훅 구성에서 와일드카드 패턴을 선택합니다.
2. 패턴을 입력합니다. 예를 들어:
   • -stable로 끝나는 브랜치를 찾으려면 *-stable.
   • production/ 네임스페이스의 브랜치를 찾으려면 production/*.

정규식 사용#

정규식으로 필터링하려면:

1. 웹훅 구성에서 정규식을 선택합니다.
2. RE2 구문을 따르는 정규식 패턴을 입력합니다.

예를 들어, main 브랜치를 제외하려면 다음을 사용합니다:

\b(?:m(?!ain\b)|ma(?!in\b)|mai(?!n\b)|[a-l]|[n-z])\w*|\b\w{1,3}\b|\W+

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

히스토리

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

PEM 형식의 전역 클라이언트 인증서를 설정하여 상호 TLS를 지원하도록 웹훅을 구성합니다.

사전 요구 사항:

• GitLab 관리자여야 합니다.

웹훅에 상호 TLS를 구성하려면:

1. PEM 형식의 클라이언트 인증서를 준비합니다.
2. 선택 사항. PEM 암호로 인증서를 보호합니다.
3. 인증서를 사용하도록 GitLab을 구성합니다.

구성 후 GitLab은 웹훅 연결을 위한 TLS 핸드셰이크 중에 서버에 이 인증서를 제공합니다.

웹훅 트래픽에 대한 방화벽 구성#

GitLab이 웹훅을 보내는 방법에 따라 웹훅 트래픽에 대한 방화벽을 구성합니다:

• Sidekiq 노드에서 비동기적으로 (가장 일반적)
• Rails 노드에서 동기적으로 (특정 경우)

UI에서 웹훅을 테스트하거나 재시도할 때 Rails 노드에서 웹훅이 동기적으로 전송됩니다.

방화벽을 구성할 때 Sidekiq와 Rails 노드 모두 웹훅 트래픽을 보낼 수 있는지 확인합니다.

웹훅 관리#

GitLab에서 구성된 웹훅을 모니터링하고 유지 관리합니다.

웹훅 요청 기록 보기#

웹훅 요청의 기록을 보고 성능을 모니터링하고 문제를 해결합니다.

사전 요구 사항:

• 프로젝트 웹훅의 경우 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.
• 그룹 웹훅의 경우 그룹에 대한 소유자 역할이 있어야 합니다.

웹훅에 대한 요청 기록을 보려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 설정 > 웹훅을 선택합니다.
3. 웹훅에 대해 편집을 선택합니다.
4. 최근 이벤트 섹션으로 이동합니다.

최근 이벤트 섹션은 지난 이틀 동안 웹훅에 대한 모든 요청을 표시합니다. 표에는 다음이 포함됩니다:

• HTTP 상태 코드:
  • 200-299 코드의 경우 녹색
  • 다른 코드의 경우 빨간색
  • 전달 실패의 경우 내부 오류
• 트리거된 이벤트
• 요청 경과 시간
• 요청이 이루어진 상대적 시간

요청 및 응답 세부 정보 검사#

사전 요구 사항:

• 프로젝트 웹훅의 경우 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.
• 그룹 웹훅의 경우 그룹에 대한 소유자 역할이 있어야 합니다.

최근 이벤트의 각 웹훅 요청에는 요청 세부 정보 페이지가 있습니다. 이 페이지에는 다음의 본문과 헤더가 포함됩니다:

• GitLab이 웹훅 수신기 엔드포인트에서 받은 응답
• GitLab이 보낸 웹훅 요청

웹훅 이벤트의 요청 및 응답 세부 정보를 검사하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 설정 > 웹훅을 선택합니다.
3. 웹훅에 대해 편집을 선택합니다.
4. 최근 이벤트 섹션으로 이동합니다.
5. 이벤트에 대해 세부 정보 보기를 선택합니다.

동일한 데이터와 동일한 Idempotency-Key 헤더로 요청을 다시 보내려면 요청 재전송을 선택합니다. 웹훅 URL이 변경된 경우 요청을 재전송할 수 없습니다. 프로젝트 웹훅 API를 통해 프로그래밍 방식으로 요청을 재전송할 수도 있습니다.

웹훅 테스트#

웹훅이 올바르게 작동하는지 확인하거나 비활성화된 웹훅을 다시 활성화하기 위해 테스트합니다.

사전 요구 사항:

• 프로젝트 웹훅의 경우 프로젝트에 대한 유지 관리자 또는 소유자 역할이 있어야 합니다.
• 그룹 웹훅의 경우 그룹에 대한 소유자 역할이 있어야 합니다.
• push events를 테스트하려면 프로젝트에 커밋이 하나 이상 있어야 합니다.

웹훅을 테스트하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 설정 > 웹훅을 선택하여 이 프로젝트의 모든 웹훅을 확인합니다.
3. 구성된 웹훅 목록에서 직접 웹훅을 테스트하려면:
   1. 테스트할 웹훅을 찾습니다.
   2. 테스트 드롭다운 목록에서 테스트할 이벤트 유형을 선택합니다.
4. 편집하면서 웹훅을 테스트하려면:
   1. 테스트할 웹훅을 찾아 편집을 선택합니다.
   2. 웹훅을 변경합니다.
   3. 테스트 드롭다운 목록을 선택한 다음 테스트할 이벤트 유형을 선택합니다.

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

웹훅 참조#

이 기술 참조를 사용하여:

• GitLab 웹훅의 작동 방식을 이해합니다.
• 시스템과 웹훅을 통합합니다.
• 웹훅 구성을 설정, 문제 해결 및 최적화합니다.

웹훅 수신기 요구 사항#

신뢰할 수 있는 웹훅 전달을 위해 빠르고 안정적인 웹훅 수신기 엔드포인트를 구현합니다.

느리거나 불안정하거나 잘못 구성된 수신기는 자동으로 비활성화될 수 있습니다. 유효하지 않은 HTTP 응답은 실패한 요청으로 처리됩니다.

웹훅 수신기를 최적화하려면:

1. 200 또는 201 상태로 신속하게 응답합니다:
   • 같은 요청에서 웹훅을 처리하는 것을 피합니다.
   • 웹훅을 받은 후 처리하기 위해 큐를 사용합니다.
   • GitLab.com에서 자동 비활성화를 방지하려면 타임아웃 한도 이전에 응답합니다.
2. 잠재적 중복 이벤트를 처리합니다:
   • 웹훅이 타임아웃되면 중복 이벤트를 준비합니다.
   • 엔드포인트가 지속적으로 빠르고 안정적인지 확인합니다.
3. 응답 헤더와 본문을 최소화합니다:
   • GitLab은 나중에 검사하기 위해 응답 헤더와 본문을 저장합니다.
   • 반환되는 헤더의 수와 크기를 제한합니다.
   • 빈 본문으로 응답하는 것을 고려합니다.
4. 적절한 상태 코드를 사용합니다:
   • 잘못 구성된 웹훅에 대해서만 클라이언트 오류 상태 응답(4xx 범위)을 반환합니다.
   • 지원되지 않는 이벤트의 경우 400을 반환하거나 페이로드를 무시합니다.
   • 처리된 이벤트에 대해 500 서버 오류 응답을 피합니다.

자동 비활성화된 웹훅#

히스토리

• GitLab 15.10에서 그룹 웹훅에 대해 도입되었습니다.
• GitLab 15.10에서 auto_disabling_web_hooks 플래그가 있는 상태로 프로젝트 웹훅에 대해 GitLab Self-Managed에서 비활성화되었습니다.
• GitLab 17.11에서 연결 실패 및 연결 실패 중이 이름 변경되어 비활성화됨 및 일시적으로 비활성화됨이 되었습니다.
• GitLab 17.11에서 40번 연속 실패 후 영구적으로 비활성화되도록 변경되었습니다.

GitLab은 4번 연속 실패한 프로젝트 또는 그룹 웹훅을 자동으로 비활성화합니다.

자동 비활성화된 웹훅을 보려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트 또는 그룹을 찾습니다.
2. 설정 > 웹훅을 선택합니다.

웹훅 목록에서 자동 비활성화된 웹훅은 다음과 같이 표시됩니다:

• 4번 연속 실패하면 일시적으로 비활성화됨
• 40번 연속 실패하면 비활성화됨

일시적으로 비활성화된 웹훅#

웹훅은 4번 연속 실패하면 일시적으로 비활성화됩니다. 40번 연속 실패하면 영구적으로 비활성화됩니다.

다음과 같은 경우에 실패가 발생합니다:

• 웹훅 수신기가 4xx 또는 5xx 범위의 응답 코드를 반환합니다.
• 웹훅이 수신기에 연결을 시도하는 동안 타임아웃이 발생합니다.
• 웹훅에 다른 HTTP 오류가 발생합니다.

일시적으로 비활성화된 웹훅은 처음에 1분 동안 비활성화되며, 이후 실패 시 최대 24시간까지 기간이 연장됩니다. 이 기간이 지나면 웹훅이 자동으로 다시 활성화됩니다.

영구적으로 비활성화된 웹훅#

웹훅은 40번 연속 실패하면 영구적으로 비활성화됩니다. 일시적으로 비활성화된 웹훅과 달리, 이러한 웹훅은 자동으로 다시 활성화되지 않습니다.

GitLab 17.10 이하에서 영구적으로 비활성화된 웹훅은 데이터 마이그레이션을 거쳤습니다. 이러한 웹훅은 UI에서 40번 실패했다고 표시될 수 있음에도 불구하고 최근 이벤트에서 4번의 실패만 표시될 수 있습니다.

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

비활성화된 웹훅을 다시 활성화하려면 테스트 요청을 보냅니다. 테스트 요청이 2xx 범위의 응답 코드를 반환하면 웹훅이 다시 활성화됩니다.

전달 헤더#

히스토리

• GitLab 16.2에서 X-Gitlab-Webhook-UUID 헤더가 도입되었습니다.
• GitLab 17.4에서 Idempotency-Key 헤더가 도입되었습니다.

GitLab은 엔드포인트에 대한 웹훅 요청에 다음 헤더를 포함합니다:

웹훅 본문의 이미지 URL 표시#

GitLab은 웹훅 본문에서 상대 이미지 참조를 절대 URL로 재작성합니다.

이미지 URL 재작성 예시#

머지 요청, 댓글 또는 위키 페이지의 원래 이미지 참조가 다음과 같다면:

![A Markdown image with a relative URL.](/uploads/$sha/image.png)

웹훅 본문에서 재작성된 이미지 참조는 다음과 같습니다:

![A Markdown image with an absolute URL.](https://gitlab.example.com/-/project/:id/uploads//image.png)

이 예시에서는 다음을 가정합니다:

• GitLab이 gitlab.example.com에 설치되어 있습니다.
• 프로젝트 ID는 123입니다.

이미지 URL 재작성의 예외#

다음과 같은 경우 GitLab은 이미지 URL을 재작성하지 않습니다:

• 이미 HTTP, HTTPS 또는 프로토콜 상대 URL을 사용하는 경우.
• 링크 레이블과 같은 고급 Markdown 기능을 사용하는 경우.

관련 항목#

• 웹훅 이벤트 및 JSON 페이로드
• 웹훅 한도
• 프로젝트 웹훅 API
• 그룹 웹훅 API
• 시스템 훅 API
• 웹훅 문제 해결
• 웹훅 및 Twilio로 SMS 알림 보내기
• GitLab 레이블 자동 적용