그룹 웹훅 API

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

REST API를 사용하여 그룹 웹훅과 상호 작용합니다. 또한 그룹 훅이라고도합니다. 이것은 시스템 전체인 시스템 후크(system hooks) 및 프로젝트별인 프로젝트 웹훅(project webhooks)과는 다릅니다.

사전 요구 사항:

  • 그룹의 관리자이거나 그룹 소유자 역할을 가지고 있어야 합니다.

그룹 훅 목록

그룹 훅 목록을 가져옵니다. 

GET /groups/:id/hooks

지원되는 속성:

속성 유형 필수 여부 설명
id 정수/문자열 예 그룹의 ID 또는 URL 인코딩 된 경로.

예시 요청: 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks"

예시 응답: 

[
  {
    "id": 1,
    "url": "http://example.com/hook",
    "name": "테스트 그룹 후크",
    "description": "이것은 테스트 그룹 후크입니다.",
    "created_at": "2024-09-01T09:10:54.854Z",
    "push_events": true,
    "tag_push_events": false,
    "merge_requests_events": false,
    "repository_update_events": false,
    "enable_ssl_verification": true,
    "alert_status": "executable",
    "disabled_until": null,
    "url_variables": [],
    "push_events_branch_filter": null,
    "branch_filter_strategy": "all_branches",
    "custom_webhook_template": "",
    "custom_headers": [],
    "group_id": 99,
    "issues_events": false,
    "confidential_issues_events": false,
    "note_events": false,
    "confidential_note_events": false,
    "pipeline_events": false,
    "wiki_page_events": false,
    "job_events": false,
    "deployment_events": false,
    "feature_flag_events": false,
    "releases_events": false,
    "subgroup_events": false,
    "emoji_events": false,
    "resource_access_token_events": false,
    "member_events": false,
    "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
    "custom_headers": [
      {
        "key": "Authorization"
      }
    ]
  }
]

그룹 후크 가져오기

그룹의 특정 후크를 가져옵니다. 

GET /groups/:id/hooks/:hook_id

지원되는 속성:

속성 유형 필수 여부 설명
id 정수/문자열 예 그룹의 ID 또는 URL 인코딩 된 경로.
hook_id 정수 예 그룹 후크의 ID.

예시 요청: 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1"

예시 응답: 

{
  "id": 1,
  "url": "http://example.com/hook",
  "name": "후크 이름",
  "description": "후크 설명",
  "group_id": 3,   
  "push_events": true,
  "push_events_branch_filter": "",
  "branch_filter_strategy": "wildcard",
  "issues_events": true,
  "confidential_issues_events": true,
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
  "confidential_note_events": true,
  "job_events": true,
  "pipeline_events": true,
  "wiki_page_events": true,
  "deployment_events": true,
  "feature_flag_events": false,
  "releases_events": true,
  "subgroup_events": true,
  "member_events": true,
  "enable_ssl_verification": true,
  "repository_update_events": false,
  "alert_status": "executable",
  "disabled_until": null,
  "url_variables": [],
  "created_at": "2012-10-12T17:04:47Z",
  "resource_access_token_events": true,
  "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
  "custom_headers": [
    {
      "key": "Authorization"
    }
  ]
}

그룹 후크 이벤트 가져오기

지난 7일 동안의 특정 그룹 후크의 이벤트 목록을 가져옵니다. 

GET /groups/:id/hooks/:hook_id/events

지원되는 속성:

속성 유형 필수 여부 설명
id 정수/문자열 예 그룹의 ID 또는 URL 인코딩 된 경로.
hook_id 정수 예 프로젝트 후크의 ID.
status 정수 또는 문자열 아니오 이벤트의 응답 상태 코드, 예: 200 또는 500. 상태 카테고리에 따라 검색할 수 있습니다: successful (200-299), client_failure (400-499), server_failure (500-599).
page 정수 아니오 가져올 페이지. 기본값은 1.
per_page 정수 아니오 페이지 당 반환할 레코드 수. 기본값은 20.

예시 요청: 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/events"

예시 응답: 

[
  {
    "id": 1,
    "url": "https://example.net/",
    "trigger": "push_hooks",
    "request_headers": {
      "Content-Type": "application/json",
      "User-Agent": "GitLab/17.1.0-pre",
      "Idempotency-Key": "a5461c4d-9c7f-4af9-add6-cddebe3c426f",
      "X-Gitlab-Event": "Push Hook",
      "X-Gitlab-Webhook-UUID": "3c5c0404-c866-44bc-a5f6-452bb1bfc76e",
      "X-Gitlab-Instance": "https://gitlab.example.com",
      "X-Gitlab-Event-UUID": "9cebe914-4827-408f-b014-cfa23a47a35f",
      "X-Gitlab-Token": "[REDACTED]"
    },
    "request_data": {
      "object_kind": "push",
      "event_name": "push"
    }
    ...
  }
  ...
]

그룹 후크 이벤트 재전송

특정 후크 이벤트를 재전송합니다.

이 엔드포인트는 각 후크 및 인증된 사용자에 대해 분당 5개의 요청 제한이 있습니다. Self-Managed GitLab 및 GitLab Dedicated에서이 제한을 해제하려면 관리자가 web_hook_event_resend_api_endpoint_rate_limit라는 기능 플래그를 비활성화 할 수 있습니다. 

POST /groups/:id/hooks/:hook_id/events/:hook_event_id/resend

지원되는 속성:

속성 유형 필수 설명
id integer/string yes 그룹의 ID 또는 URL-encoded path.
hook_id integer Yes 그룹 후크의 ID.
hook_event_id integer Yes 후크 이벤트의 ID.

예시 요청: 

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/events/1/resend"

예시 응답: 

{
  "response_status": 200
}

그룹 후크 추가

특정 그룹에 후크를 추가합니다. 

POST /groups/:id/hooks

지원되는 속성:

속성 유형 필수 설명
id integer/string yes 그룹의 ID 또는 URL-encoded path.
url string yes 후크 URL.
name string no 후크 이름 (GitLab 17.1에 소개).
description string no 후크 설명 (GitLab 17.1에 소개).
push_events boolean no 푸시 이벤트에서 후크 트리거.
push_events_branch_filter string no 특정 브랜치에 대한 푸시 이벤트에서 후크 트리거.
branch_filter_strategy string no 브랜치별 푸시 이벤트 필터링. wildcard(기본), regex, all_branches의 가능한 값.
issues_events boolean no 이슈 이벤트에서 후크 트리거.
confidential_issues_events boolean no 비밀 이슈 이벤트에서 후크 트리거.
merge_requests_events boolean no 병합 요청 이벤트에서 후크 트리거.
tag_push_events boolean no 태그 푸시 이벤트에서 후크 트리거.
note_events boolean no 노트 이벤트에서 후크 트리거.
confidential_note_events boolean no 비밀 노트 이벤트에서 후크 트리거.
job_events boolean no 작업 이벤트에서 후크 트리거.
pipeline_events boolean no 파이프라인 이벤트에서 후크 트리거.
wiki_page_events boolean no 위키 페이지 이벤트에서 후크 트리거.
deployment_events boolean no 배포 이벤트에서 후크 트리거.
feature_flag_events boolean no 기능 플래그 이벤트에서 후크 트리거.
releases_events boolean no 릴리스 이벤트에서 후크 트리거.
subgroup_events boolean no 하위 그룹 이벤트에서 후크 트리거.
member_events boolean no 멤버 이벤트에서 후크 트리거.
enable_ssl_verification boolean no 후크 트리거시 SSL 확인 수행.
token string no 수신된 페이로드를 확인하기 위한 비밀 토큰; 응답에는 표시되지 않음.
resource_access_token_events boolean no 프로젝트 접근 토큰 만료 이벤트에서 후크 트리거.
custom_webhook_template string no 후크용 사용자 정의 웹훅 템플릿.
custom_headers array No 후크용 사용자 정의 헤더.

예시 요청: 

curl --request POST \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/hooks" \
  --data '{"url": "https://example.com/hook", "name": "My Hook", "description": "Hook description"}'

예시 응답: 

{
  "id": 42,
  "url": "https://example.com/hook",
  "name": "My Hook",
  "description": "Hook description",
  "group_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "branch_filter_strategy": "wildcard",
  "issues_events": true,
  "confidential_issues_events": true,
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
  "confidential_note_events": true,
  "job_events": true,
  "pipeline_events": true,
  "wiki_page_events": true,
  "deployment_events": true,
  "feature_flag_events": true,
  "releases_events": true,
  "subgroup_events": true,
  "member_events": true,
  "enable_ssl_verification": true,
  "repository_update_events": false,
  "alert_status": "executable",
  "disabled_until": null,
  "url_variables": [ ],
  "created_at": "2012-10-12T17:04:47Z",
  "resource_access_token_events": true,
  "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}"
}

그룹 후크 편집

지정된 그룹의 후크를 편집합니다. 

PUT /groups/:id/hooks/:hook_id

지원되는 속성:

속성 유형 필수 여부 설명
id 정수 또는 문자열 예 그룹의 ID 또는 URL 인코딩 된 경로.
hook_id 정수 예 그룹 훅의 ID.
url 문자열 예 후크의 URL.
name 문자열 아니오 후크의 이름 (GitLab 17.1에서 도입됨).
description 문자열 아니오 후크의 설명 (GitLab 17.1에서 도입됨).
push_events 부울 아니오 푸시 이벤트에서 후크 트리거.
push_events_branch_filter 문자열 아니오 일치하는 브랜치에서 푸시 이벤트에서 후크 트리거.
branch_filter_strategy 문자열 아니오 브랜치별 푸시 이벤트 필터링. wildcard (기본값), regex, all_branches 중 가능한 값.
issues_events 부울 아니오 이슈 이벤트에서 후크 트리거.
confidential_issues_events 부울 아니오 기밀 이슈 이벤트에서 후크 트리거.
merge_requests_events 부울 아니오 병합 요청 이벤트에서 후크 트리거.
tag_push_events 부울 아니오 태그 푸시 이벤트에서 후크 트리거.
note_events 부울 아니오 노트 이벤트에서 후크 트리거.
confidential_note_events 부울 아니오 기밀 노트 이벤트에서 후크 트리거.
job_events 부울 아니오 작업 이벤트에서 후크 트리거.
pipeline_events 부울 아니오 파이프라인 이벤트에서 후크 트리거.
wiki_page_events 부울 아니오 위키 페이지 이벤트에서 후크 트리거.
deployment_events 부울 아니오 배포 이벤트에서 후크 트리거.
feature_flag_events 부울 아니오 기능 플래그 이벤트에서 후크 트리거.
releases_events 부울 아니오 릴리스 이벤트에서 후크 트리거.
subgroup_events 부울 아니오 하위 그룹 이벤트에서 후크 트리거.
member_events 부울 아니오 멤버 이벤트에서 후크 트리거.
enable_ssl_verification 부울 아니오 후크를 트리거할 때 SSL 검증 수행.
service_access_tokens_expiration_enforced 부울 아니오 서비스 계정 액세스 토큰이 만료일을 가져야 하는지 여부.
token 문자열 아니오 수신된 페이로드를 유효성 검사하는 비밀 토큰. 응답에는 반환되지 않음. 웹훅 URL을 변경하면 시크릿 토큰이 재설정되고 유지되지 않음.
resource_access_token_events 부울 아니오 프로젝트 액세스 토큰 만료 이벤트에서 후크 트리거.
custom_webhook_template 문자열 아니오 후크를 위한 사용자 정의 웹훅 템플릿.
custom_headers 배열 아니오 후크를 위한 사용자 정의 헤더.

예제 요청: 

curl --request POST \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/hooks/1" \
  --data '{"url": "https://example.com/hook", "name": "New hook name", "description": "Changed hook description"}'

예제 응답: 

{
  "id": 1,
  "url": "https://example.com/hook",
  "name": "New hook name",
  "description": "Changed hook description",
  "group_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "branch_filter_strategy": "wildcard",
  "issues_events": true,
  "confidential_issues_events": true,
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
  "confidential_note_events": true,
  "job_events": true,
  "pipeline_events": true,
  "wiki_page_events": true,
  "deployment_events": true,
  "feature_flag_events": true,
  "releases_events": true,
  "subgroup_events": true,
  "member_events": true,
  "enable_ssl_verification": true,
  "repository_update_events": false,
  "alert_status": "executable",
  "disabled_until": null,
  "url_variables": [ ],
  "created_at": "2012-10-12T17:04:47Z",
  "resource_access_token_events": true,
  "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
  "custom_headers": [
    {
      "key": "Authorization"
    }
  ]
}

그룹 후크 삭제

그룹에서 후크를 삭제합니다. 이 메서드는 멱등성을 가지며 여러 번 호출할 수 있습니다. 훅이 있는지 여부에 관계없이 작동합니다. 

DELETE /groups/:id/hooks/:hook_id

지원되는 속성:

속성 유형 필수 여부 설명
id 정수 또는 문자열 예 그룹의 ID 또는 URL 인코딩 된 경로.
hook_id 정수 예 그룹 후크의 ID.

예제 요청: 

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1"

성공 시, 메시지가 반환되지 않습니다.

테스트 그룹 후크 트리거

지정된 그룹의 테스트 후크를 트리거합니다.

이 엔드포인트는 각 그룹 및 인증된 사용자당 분당 다섯 번의 요청 속도 제한이 있습니다. 자체 관리형 GitLab 및 GitLab Dedicated의 경우 이 제한을 해제하려면 관리자가 web_hook_test_api_endpoint_rate_limit라는 피처 플래그를 비활성화할 수 있습니다. 

POST /groups/:id/hooks/:hook_id/test/:trigger
속성 유형 필수 여부 설명
hook_id 정수 예 그룹 후크의 ID.
id 정수 또는 문자열 예 그룹의 ID 또는 URL 인코딩 된 경로.
trigger 문자열 예 push_events, tag_push_events, issues_events, confidential_issues_events, note_events, merge_requests_events, job_events, pipeline_events, wiki_page_events, releases_events, emoji_events, resource_access_token_events 중 하나.

예제 요청: 

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/test/push_events"

예제 응답: 

{"message":"201 Created"}

사용자 정의 헤더 설정

  • 소개: GitLab 17.1에서 도입되었습니다.

사용자 정의 헤더를 설정합니다. 

PUT /groups/:id/hooks/:hook_id/custom_headers/:key

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 그룹의 ID 또는 URL-인코딩된 경로.
hook_id 정수 예 그룹 훅의 ID.
key 문자열 예 사용자 정의 헤더의 키.
value 문자열 예 사용자 정의 헤더의 값.

예시 요청: 

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/custom_headers/header_key?value='header_value'"

성공하면 메시지가 반환되지 않습니다.

사용자 정의 헤더 삭제

  • 소개: GitLab 17.1에서 도입되었습니다.

사용자 정의 헤더를 삭제합니다. 

DELETE /groups/:id/hooks/:hook_id/custom_headers/:key

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 그룹의 ID 또는 URL-인코딩된 경로.
hook_id 정수 예 그룹 훅의 ID.
key 문자열 예 사용자 정의 헤더의 키.

예시 요청: 

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/custom_headers/header_key"

성공하면 메시지가 반환되지 않습니다.

URL 변수 설정

  • 소개: GitLab 15.2에서 도입되었습니다. 
PUT /groups/:id/hooks/:hook_id/url_variables/:key

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 그룹의 ID 또는 URL-인코딩된 경로.
hook_id 정수 예 그룹 훅의 ID.
key 문자열 예 URL 변수의 키.
value 문자열 예 URL 변수의 값.

예시 요청: 

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/url_variables/my_key?value='my_key_value'"

성공하면 메시지가 반환되지 않습니다.

URL 변수 삭제

  • 소개: GitLab 15.2에서 도입되었습니다. 
DELETE /groups/:id/hooks/:hook_id/url_variables/:key

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 그룹의 ID 또는 URL-인코딩된 경로.
hook_id 정수 예 그룹 훅의 ID.
key 문자열 예 URL 변수의 키.

예시 요청: 

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/url_variables/my_key"

성공하면 메시지가 반환되지 않습니다.