시스템 훅 API

요약

이 API를 사용하여 시스템 훅을 관리합니다. signing_token 속성의 사용 가능 여부는 기능 플래그로 제어됩니다. 모의 데이터로 시스템 훅을 실행합니다. 성공 시 이 엔드포인트는 응답 코드 204 No Content를 반환합니다.

이 API를 사용하여 시스템 훅을 관리합니다. 시스템 훅은 그룹의 모든 프로젝트와 서브그룹에 영향을 미치는 그룹 웹훅, 단일 프로젝트로 제한된 프로젝트 웹훅과는 다릅니다.

사전 요건:

관리자여야 합니다.

모든 시스템 훅 목록 조회#

모든 시스템 훅을 나열합니다.

GET /hooks

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks"

응답 예시:

[
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification":true,
    "url_variables": [],
    "token_present": false,
    "signing_token_present": false
  }
]

히스토리

name 및 description 속성이 GitLab 17.1에서 도입되었습니다.
token_present 및 signing_token_present 속성이 GitLab 19.0에서 도입되었습니다.

시스템 훅 조회#

ID로 시스템 훅을 조회합니다.

GET /hooks/:id

속성	유형	필수 여부	설명
`id`	integer	예	훅의 ID.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/1"

응답 예시:

{
  "id": 1,
  "url": "https://gitlab.example.com/hook",
  "name": "Hook name",
  "description": "Hook description",
  "created_at": "2016-10-31T12:32:15.192Z",
  "push_events": true,
  "tag_push_events": false,
  "merge_requests_events": true,
  "repository_update_events": true,
  "enable_ssl_verification": true,
  "url_variables": [],
  "token_present": false,
  "signing_token_present": false
}

히스토리

name 및 description 속성이 GitLab 17.1에서 도입되었습니다.
token_present 및 signing_token_present 속성이 GitLab 19.0에서 도입되었습니다.

새 시스템 훅 추가#

히스토리

name 및 description 속성이 GitLab 17.1에서 도입되었습니다.
signing_token 속성이 GitLab 19.0에서 webhook_signing_token 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화.

Note

signing_token 속성의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 history를 참조하세요.

새 시스템 훅을 추가합니다.

POST /hooks

속성	유형	필수 여부	설명
`url`	string	예	훅 URL.
`branch_filter_strategy`	string	아니요	브랜치로 푸시 이벤트를 필터링합니다. 가능한 값은 `wildcard`(기본값), `regex`, `all_branches`입니다.
`description`	string	아니요	훅 설명.
`enable_ssl_verification`	boolean	아니요	훅을 트리거할 때 SSL 검증을 수행합니다.
`merge_requests_events`	boolean	아니요	머지 리퀘스트 이벤트 시 훅을 트리거합니다.
`name`	string	아니요	훅 이름.
`push_events`	boolean	아니요	true이면 푸시 이벤트 시 훅이 실행됩니다.
`push_events_branch_filter`	string	아니요	일치하는 브랜치에 대한 푸시 이벤트에만 훅을 트리거합니다.
`repository_update_events`	boolean	아니요	리포지터리 업데이트 이벤트 시 훅을 트리거합니다.
`signing_token`	string	아니요	webhook-signature 헤더를 계산하는 데 사용되는 HMAC 서명 토큰. 32바이트 키를 인코딩하는 `whsec_<base64>` 형식이어야 합니다. 응답에는 반환되지 않습니다.
`tag_push_events`	boolean	아니요	true이면 새 태그가 푸시될 때 훅이 실행됩니다.
`token`	string	아니요	수신 페이로드를 검증하기 위한 시크릿 토큰. 응답에는 반환되지 않습니다.

요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks?url=https://gitlab.example.com/hook"

응답 예시:

[
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification":true,
    "url_variables": [],
    "token_present": false,
    "signing_token_present": false
  }
]

시스템 훅 업데이트#

히스토리

name 및 description 속성이 GitLab 17.1에서 도입되었습니다.
signing_token 속성이 GitLab 19.0에서 webhook_signing_token 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화.

Note

signing_token 속성의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 history를 참조하세요.

기존 시스템 훅을 업데이트합니다.

PUT /hooks/:hook_id

속성	유형	필수 여부	설명
`hook_id`	integer	예	시스템 훅의 ID.
`branch_filter_strategy`	string	아니요	브랜치로 푸시 이벤트를 필터링합니다. 가능한 값은 `wildcard`(기본값), `regex`, `all_branches`입니다.
`description`	string	아니요	훅 설명.
`enable_ssl_verification`	boolean	아니요	훅을 트리거할 때 SSL 검증을 수행합니다.
`merge_requests_events`	boolean	아니요	머지 리퀘스트 이벤트 시 훅을 트리거합니다.
`name`	string	아니요	훅 이름.
`push_events`	boolean	아니요	true이면 푸시 이벤트 시 훅이 실행됩니다.
`push_events_branch_filter`	string	아니요	일치하는 브랜치에 대한 푸시 이벤트에만 훅을 트리거합니다.
`repository_update_events`	boolean	아니요	리포지터리 업데이트 이벤트 시 훅을 트리거합니다.
`signing_token`	string	아니요	webhook-signature 헤더를 계산하는 데 사용되는 HMAC 서명 토큰. 32바이트 키를 인코딩하는 `whsec_<base64>` 형식이어야 합니다. 응답에는 반환되지 않습니다.
`tag_push_events`	boolean	아니요	true이면 새 태그가 푸시될 때 훅이 실행됩니다.
`token`	string	아니요	수신 페이로드를 검증하기 위한 시크릿 토큰. 응답에는 반환되지 않습니다.
`url`	string	아니요	훅 URL.

시스템 훅 테스트#

모의 데이터로 시스템 훅을 실행합니다.

POST /hooks/:id

속성	유형	필수 여부	설명
`id`	integer	예	훅의 ID.

요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/1"

응답은 항상 모의 데이터입니다:

{
   "project_id" : 1,
   "owner_email" : "example@gitlabhq.com",
   "owner_name" : "Someone",
   "name" : "Ruby",
   "path" : "ruby",
   "event_name" : "project_create"
}

시스템 훅 삭제#

시스템 훅을 삭제합니다.

DELETE /hooks/:id

속성	유형	필수 여부	설명
`id`	integer	예	훅의 ID.

요청 예시:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/2"

URL 변수 설정#

PUT /hooks/:hook_id/url_variables/:key

지원되는 속성:

속성	유형	필수 여부	설명
`hook_id`	integer	예	시스템 훅의 ID.
`key`	string	예	URL 변수의 키.
`value`	string	예	URL 변수의 값.

성공 시 이 엔드포인트는 응답 코드 204 No Content를 반환합니다.

URL 변수 삭제#

DELETE /hooks/:hook_id/url_variables/:key

지원되는 속성:

속성	유형	필수 여부	설명
`hook_id`	integer	예	시스템 훅의 ID.
`key`	string	예	URL 변수의 키.

성공 시 이 엔드포인트는 응답 코드 204 No Content를 반환합니다.

시스템 훅 API

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

원문 보기

번역일: 2026-05-22

요약

사전 요건:

관리자여야 합니다.

모든 시스템 훅 목록 조회#

모든 시스템 훅을 나열합니다.

GET /hooks

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks"

응답 예시:

[
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification":true,
    "url_variables": [],
    "token_present": false,
    "signing_token_present": false
  }
]

히스토리

name 및 description 속성이 GitLab 17.1에서 도입되었습니다.
token_present 및 signing_token_present 속성이 GitLab 19.0에서 도입되었습니다.

시스템 훅 조회#

ID로 시스템 훅을 조회합니다.

GET /hooks/:id

속성	유형	필수 여부	설명
`id`	integer	예	훅의 ID.

요청 예시:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/1"

응답 예시:

{
  "id": 1,
  "url": "https://gitlab.example.com/hook",
  "name": "Hook name",
  "description": "Hook description",
  "created_at": "2016-10-31T12:32:15.192Z",
  "push_events": true,
  "tag_push_events": false,
  "merge_requests_events": true,
  "repository_update_events": true,
  "enable_ssl_verification": true,
  "url_variables": [],
  "token_present": false,
  "signing_token_present": false
}

히스토리

name 및 description 속성이 GitLab 17.1에서 도입되었습니다.
token_present 및 signing_token_present 속성이 GitLab 19.0에서 도입되었습니다.

새 시스템 훅 추가#

히스토리

name 및 description 속성이 GitLab 17.1에서 도입되었습니다.
signing_token 속성이 GitLab 19.0에서 webhook_signing_token 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화.

Note

signing_token 속성의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 history를 참조하세요.

새 시스템 훅을 추가합니다.

POST /hooks

속성	유형	필수 여부	설명
`url`	string	예	훅 URL.
`branch_filter_strategy`	string	아니요	브랜치로 푸시 이벤트를 필터링합니다. 가능한 값은 `wildcard`(기본값), `regex`, `all_branches`입니다.
`description`	string	아니요	훅 설명.
`enable_ssl_verification`	boolean	아니요	훅을 트리거할 때 SSL 검증을 수행합니다.
`merge_requests_events`	boolean	아니요	머지 리퀘스트 이벤트 시 훅을 트리거합니다.
`name`	string	아니요	훅 이름.
`push_events`	boolean	아니요	true이면 푸시 이벤트 시 훅이 실행됩니다.
`push_events_branch_filter`	string	아니요	일치하는 브랜치에 대한 푸시 이벤트에만 훅을 트리거합니다.
`repository_update_events`	boolean	아니요	리포지터리 업데이트 이벤트 시 훅을 트리거합니다.
`signing_token`	string	아니요	webhook-signature 헤더를 계산하는 데 사용되는 HMAC 서명 토큰. 32바이트 키를 인코딩하는 `whsec_<base64>` 형식이어야 합니다. 응답에는 반환되지 않습니다.
`tag_push_events`	boolean	아니요	true이면 새 태그가 푸시될 때 훅이 실행됩니다.
`token`	string	아니요	수신 페이로드를 검증하기 위한 시크릿 토큰. 응답에는 반환되지 않습니다.

요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks?url=https://gitlab.example.com/hook"

응답 예시:

[
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification":true,
    "url_variables": [],
    "token_present": false,
    "signing_token_present": false
  }
]

시스템 훅 업데이트#

히스토리

name 및 description 속성이 GitLab 17.1에서 도입되었습니다.
signing_token 속성이 GitLab 19.0에서 webhook_signing_token 기능 플래그와 함께 도입되었습니다. 기본적으로 활성화.

Note

signing_token 속성의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 history를 참조하세요.

기존 시스템 훅을 업데이트합니다.

PUT /hooks/:hook_id

속성	유형	필수 여부	설명
`hook_id`	integer	예	시스템 훅의 ID.
`branch_filter_strategy`	string	아니요	브랜치로 푸시 이벤트를 필터링합니다. 가능한 값은 `wildcard`(기본값), `regex`, `all_branches`입니다.
`description`	string	아니요	훅 설명.
`enable_ssl_verification`	boolean	아니요	훅을 트리거할 때 SSL 검증을 수행합니다.
`merge_requests_events`	boolean	아니요	머지 리퀘스트 이벤트 시 훅을 트리거합니다.
`name`	string	아니요	훅 이름.
`push_events`	boolean	아니요	true이면 푸시 이벤트 시 훅이 실행됩니다.
`push_events_branch_filter`	string	아니요	일치하는 브랜치에 대한 푸시 이벤트에만 훅을 트리거합니다.
`repository_update_events`	boolean	아니요	리포지터리 업데이트 이벤트 시 훅을 트리거합니다.
`signing_token`	string	아니요	webhook-signature 헤더를 계산하는 데 사용되는 HMAC 서명 토큰. 32바이트 키를 인코딩하는 `whsec_<base64>` 형식이어야 합니다. 응답에는 반환되지 않습니다.
`tag_push_events`	boolean	아니요	true이면 새 태그가 푸시될 때 훅이 실행됩니다.
`token`	string	아니요	수신 페이로드를 검증하기 위한 시크릿 토큰. 응답에는 반환되지 않습니다.
`url`	string	아니요	훅 URL.

시스템 훅 테스트#

모의 데이터로 시스템 훅을 실행합니다.

POST /hooks/:id

속성	유형	필수 여부	설명
`id`	integer	예	훅의 ID.

요청 예시:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/1"

응답은 항상 모의 데이터입니다:

{
   "project_id" : 1,
   "owner_email" : "example@gitlabhq.com",
   "owner_name" : "Someone",
   "name" : "Ruby",
   "path" : "ruby",
   "event_name" : "project_create"
}

시스템 훅 삭제#

시스템 훅을 삭제합니다.

DELETE /hooks/:id

속성	유형	필수 여부	설명
`id`	integer	예	훅의 ID.

요청 예시:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/2"

URL 변수 설정#

PUT /hooks/:hook_id/url_variables/:key

지원되는 속성:

속성	유형	필수 여부	설명
`hook_id`	integer	예	시스템 훅의 ID.
`key`	string	예	URL 변수의 키.
`value`	string	예	URL 변수의 값.

성공 시 이 엔드포인트는 응답 코드 204 No Content를 반환합니다.

URL 변수 삭제#

DELETE /hooks/:hook_id/url_variables/:key

지원되는 속성:

속성	유형	필수 여부	설명
`hook_id`	integer	예	시스템 훅의 ID.
`key`	string	예	URL 변수의 키.

성공 시 이 엔드포인트는 응답 코드 204 No Content를 반환합니다.