프로젝트 웹훅

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

REST API를 사용하여 프로젝트 웹훅을 관리하세요. 프로젝트 웹훅은 시스템 전체에 적용되는 시스템 훅과 다르며, 그룹 웹훅과도 다릅니다.

사전 요구 사항:

  • 프로젝트의 관리자로 있거나 최소한 Maintainer 역할이 있어야 합니다.

프로젝트에 대한 웹훅 목록 가져오기

프로젝트 웹훅의 목록을 가져옵니다.

GET /projects/:id/hooks

지원되는 속성:

Attribute Type Required Description
id integer or string Yes 프로젝트의 ID 또는 URL로 인코딩된 경로.

프로젝트 웹훅 가져오기

프로젝트의 특정 웹훅을 가져옵니다.

GET /projects/:id/hooks/:hook_id

지원되는 속성:

Attribute Type Required Description
hook_id integer Yes 프로젝트 웹훅의 ID입니다.
id integer or string Yes 프로젝트의 ID 또는 URL로 인코딩된 경로.

예시 응답:

{
  "id": 1,
  "url": "http://example.com/hook",
  "name": "Hook name",
  "description": "Hook description",
  "project_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "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,
  "releases_events": true,
  "feature_flag_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 /projects/:id/hooks/:hook_id/events

지원되는 속성:

Attribute Type Required Description
hook_id integer Yes 프로젝트 웹훅의 ID입니다.
id integer or string Yes 프로젝트의 ID 또는 URL로 인코딩된 경로.
status integer or string No 이벤트의 응답 상태 코드, 예: 200 또는 500. 상태 카테고리로 검색할 수 있습니다: successful (200-299), client_failure (400-499), server_failure (500-599).
page integer No 검색할 페이지입니다. 기본값은 1입니다.
per_page integer No 페이지당 반환할 기록 수입니다. 기본값은 20입니다.

예시 응답:

[
  {
    "id": 1,
    "url": "https://example.net/",
    "trigger": "push_hooks",
    "request_headers": {
      "Content-Type": "application/json",
      "User-Agent": "GitLab/17.1.0-pre",
      "Idempotency-Key": "3a427872-00df-429c-9bc9-a9475de2efe4",
      "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",
      "before": "468abc807a2b2572f43e72c743b76cee6db24025",
      "after": "f15b32277d2c55c6c595845a87109b09c913c556",
      "ref": "refs/heads/master",
      "ref_protected": true,
      "checkout_sha": "f15b32277d2c55c6c595845a87109b09c913c556",
      "message": null,
      "user_id": 1,
      "user_name": "Administrator",
      "user_username": "root",
      "user_email": null,
      "user_avatar": "https://www.gravatar.com/avatar/13efe0d4559475ba84ecc802061febbdea6e224fcbffd7ec7da9cd431845299c?s=80&d=identicon",
      "project_id": 7,
      "project": {
        "id": 7,
        "name": "Flight",
        "description": "Incidunt ea ab officia a veniam.",
        "web_url": "https://gitlab.example.com/flightjs/Flight",
        "avatar_url": null,
        "git_ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "git_http_url": "https://gitlab.example.com/flightjs/Flight.git",
        "namespace": "Flightjs",
        "visibility_level": 10,
        "path_with_namespace": "flightjs/Flight",
        "default_branch": "master",
        "ci_config_path": null,
        "homepage": "https://gitlab.example.com/flightjs/Flight",
        "url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "http_url": "https://gitlab.example.com/flightjs/Flight.git"
      },
      "commits": [
        {
          "id": "f15b32277d2c55c6c595845a87109b09c913c556",
          "message": "v1.5.2\n",
          "title": "v1.5.2",
          "timestamp": "2017-06-19T14:39:53-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/f15b32277d2c55c6c595845a87109b09c913c556",
          "author": {
            "name": "Andrew Lunny",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        },
        {
          "id": "8749d49930866a4871fa086adbd7d2057fcc3ebb",
          "message": "Merge pull request #378 from flightjs/alunny/publish_lib\n\npublish lib and index to npm",
          "title": "Merge pull request #378 from flightjs/alunny/publish_lib",
          "timestamp": "2017-06-16T10:26:39-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/8749d49930866a4871fa086adbd7d2057fcc3ebb",
          "author": {
            "name": "angus croll",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        },
        {
          "id": "468abc807a2b2572f43e72c743b76cee6db24025",
          "message": "publish lib and index to npm\n",
          "title": "publish lib and index to npm",
          "timestamp": "2017-06-16T10:23:04-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/468abc807a2b2572f43e72c743b76cee6db24025",
          "author": {
            "name": "Andrew Lunny",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        }
      ],
      "total_commits_count": 3,
      "push_options": {},
      "repository": {
        "name": "Flight",
        "url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "description": "Incidunt ea ab officia a veniam.",
        "homepage": "https://gitlab.example.com/flightjs/Flight",
        "git_http_url": "https://gitlab.example.com/flightjs/Flight.git",
        "git_ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "visibility_level": 10
      }
    },
    "response_headers": {
      "Date": "Sun, 26 May 2024 03:03:17 GMT",
      "Content-Type": "application/json; charset=utf-8",
      "Content-Length": "16",
      "Connection": "close",
      "X-Powered-By": "Express",
      "Access-Control-Allow-Origin": "*",
      "X-Pd-Status": "sent to primary"
    },
    "response_body": "{\"success\":true}",
    "execution_duration": 1.0906479999999874,
    "response_status": "200"
  },
  {
    "id": 2,
    "url": "https://example.net/",
    "trigger": "push_hooks",
    "request_headers": {
      "Content-Type": "application/json",
      "User-Agent": "GitLab/17.1.0-pre",
      "Idempotency-Key": "7c6e0583-49f2-4dc5-a50b-4c0bcf3c1b27",
      "X-Gitlab-Event": "Push Hook",
      "X-Gitlab-Webhook-UUID": "a753eedb-1d72-4549-9ca7-eac8ea8e50dd",
      "X-Gitlab-Instance": "https://gitlab.example.com",
      "X-Gitlab-Event-UUID": "842d7c3e-3114-4396-8a95-66c084d53cb1",
      "X-Gitlab-Token": "[REDACTED]"
    },
    "request_data": {
      "object_kind": "push",
      "event_name": "push",
      "before": "468abc807a2b2572f43e72c743b76cee6db24025",
      "after": "f15b32277d2c55c6c595845a87109b09c913c556",
      "ref": "refs/heads/master",
      "ref_protected": true,
      "checkout_sha": "f15b32277d2c55c6c595845a87109b09c913c556",
      "message": null,
      "user_id": 1,
      "user_name": "Administrator",
      "user_username": "root",
      "user_email": null,
      "user_avatar": "https://www.gravatar.com/avatar/13efe0d4559475ba84ecc802061febbdea6e224fcbffd7ec7da9cd431845299c?s=80&d=identicon",
      "project_id": 7,
      "project": {
        "id": 7,
        "name": "Flight",
        "description": "Incidunt ea ab officia a veniam.",
        "web_url": "https://gitlab.example.com/flightjs/Flight",
        "avatar_url": null,
        "git_ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "git_http_url": "https://gitlab.example.com/flightjs/Flight.git",
        "namespace": "Flightjs",
        "visibility_level": 10,
        "path_with_namespace": "flightjs/Flight",
        "default_branch": "master",
        "ci_config_path": null,
        "homepage": "https://gitlab.example.com/flightjs/Flight",
        "url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "http_url": "https://gitlab.example.com/flightjs/Flight.git"
      },
      "commits": [
        {
          "id": "f15b32277d2c55c6c595845a87109b09c913c556",
          "message": "v1.5.2\n",
          "title": "v1.5.2",
          "timestamp": "2017-06-19T14:39:53-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/f15b32277d2c55c6c595845a87109b09c913c556",
          "author": {
            "name": "Andrew Lunny",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        },
        {
          "id": "8749d49930866a4871fa086adbd7d2057fcc3ebb",
          "message": "Merge pull request #378 from flightjs/alunny/publish_lib\n\npublish lib and index to npm",
          "title": "Merge pull request #378 from flightjs/alunny/publish_lib",
          "timestamp": "2017-06-16T10:26:39-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/8749d49930866a4871fa086adbd7d2057fcc3ebb",
          "author": {
            "name": "angus croll",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        },
        {
          "id": "468abc807a2b2572f43e72c743b76cee6db24025",
          "message": "publish lib and index to npm\n",
          "title": "publish lib and index to npm",
          "timestamp": "2017-06-16T10:23:04-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/468abc807a2b2572f43e72c743b76cee6db24025",
          "author": {
            "name": "Andrew Lunny",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        }
      ],
      "total_commits_count": 3,
      "push_options": {},
      "repository": {
        "name": "Flight",
        "url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "description": "Incidunt ea ab officia a veniam.",
        "homepage": "https://gitlab.example.com/flightjs/Flight",
        "git_http_url": "https://gitlab.example.com/flightjs/Flight.git",
        "git_ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "visibility_level": 10
      }
    },
    "response_headers": {
      "Date": "Sun, 26 May 2024 03:03:19 GMT",
      "Content-Type": "application/json; charset=utf-8",
      "Content-Length": "16",
      "Connection": "close",
      "X-Powered-By": "Express",
      "Access-Control-Allow-Origin": "*",
      "X-Pd-Status": "sent to primary"
    },
    "response_body": "{\"success\":true}",
    "execution_duration": 1.0716120000000728,
    "response_status": "200"
  }
]

프로젝트 웹후크 이벤트 재전송

특정 프로젝트 웹후크 이벤트를 재전송합니다.

이 엔드포인트는 각 프로젝트 웹후크와 인증된 사용자에 대해 분당 다섯 건의 요청으로 제한됩니다.

자체 관리 GitLab 및 GitLab 전용에서 이 제한을 비활성화하려면, 관리자가 web_hook_event_resend_api_endpoint_rate_limit이라는 기능 플래그를 비활성화할 수 있습니다.

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

지원되는 속성:

속성 유형 필수 설명
hook_id integer 예 프로젝트 웹후크의 ID.
hook_event_id integer 예 프로젝트 웹후크 이벤트의 ID.

예시 응답:

{
  "response_status": 200
}

프로젝트에 웹후크 추가

  • name 및 description 속성이 GitLab 17.1에서 도입됨.

지정된 프로젝트에 웹후크를 추가합니다.

POST /projects/:id/hooks

지원되는 속성:

속성 유형 필수 설명
id integer 또는 string 예 프로젝트의 ID 또는 URL-인코딩된 경로입니다.
url string 예 프로젝트 웹후크 URL.
name string 아니요 프로젝트 웹후크의 이름.
description string 아니요 웹후크의 설명.
confidential_issues_events boolean 아니요 기밀 이슈 이벤트에서 프로젝트 웹후크를 트리거합니다.
confidential_note_events boolean 아니요 기밀 노트 이벤트에서 프로젝트 웹후크를 트리거합니다.
deployment_events boolean 아니요 배포 이벤트에서 프로젝트 웹후크를 트리거합니다.
enable_ssl_verification boolean 아니요 웹후크를 트리거할 때 SSL 검증을 수행합니다.
feature_flag_events boolean 아니요 기능 플래그 이벤트에서 프로젝트 웹후크를 트리거합니다.
issues_events boolean 아니요 이슈 이벤트에서 프로젝트 웹후크를 트리거합니다.
job_events boolean 아니요 작업 이벤트에서 프로젝트 웹후크를 트리거합니다.
merge_requests_events boolean 아니요 병합 요청 이벤트에서 프로젝트 웹후크를 트리거합니다.
note_events boolean 아니요 노트 이벤트에서 프로젝트 웹후크를 트리거합니다.
pipeline_events boolean 아니요 파이프라인 이벤트에서 프로젝트 웹후크를 트리거합니다.
push_events_branch_filter string 아니요 일치하는 지점에 대해서만 푸시 이벤트에서 프로젝트 웹후크를 트리거합니다.
branch_filter_strategy string 아니요 분기별로 푸시 이벤트를 필터링합니다. 가능한 값은 wildcard(기본값), regex, 및 all_branches입니다.
push_events boolean 아니요 푸시 이벤트에서 프로젝트 웹후크를 트리거합니다.
releases_events boolean 아니요 릴리스 이벤트에서 프로젝트 웹후크를 트리거합니다.
tag_push_events boolean 아니요 태그 푸시 이벤트에서 프로젝트 웹후크를 트리거합니다.
token string 아니요 수신된 페이로드를 검증하기 위한 비밀 토큰; 응답에 토큰이 반환되지 않습니다.
wiki_page_events boolean 아니요 위키 이벤트에서 프로젝트 웹후크를 트리거합니다.
resource_access_token_events boolean 아니요 프로젝트 접근 토큰 만료 이벤트에서 프로젝트 웹후크를 트리거합니다.
custom_webhook_template string 아니요 프로젝트 웹후크에 대한 사용자 정의 웹후크 템플릿.
custom_headers array 아니요 프로젝트 웹후크에 대한 사용자 정의 헤더.

프로젝트 웹훅 편집하기

  • name 및 description 속성 도입됨 GitLab 17.1에서.

지정된 프로젝트에 대한 웹훅을 편집합니다.

PUT /projects/:id/hooks/:hook_id

지원되는 속성:

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

프로젝트 웹훅 삭제하기

프로젝트에서 웹훅을 제거합니다. 이 방법은 멱등성이 있으며 여러 번 호출할 수 있습니다. 프로젝트 웹훅은 존재하거나 존재하지 않습니다.

DELETE /projects/:id/hooks/:hook_id

지원되는 속성:

속성 유형 필수 설명
hook_id 정수 예 프로젝트 웹훅의 ID.
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로.

프로젝트 웹훅의 존재 여부에 따라 JSON 응답이 다릅니다. 프로젝트 훅이 JSON 응답으로 반환되기 전에 사용 가능한 경우 또는 빈 응답이 반환됩니다.

테스트 프로젝트 웹후크 트리거

  • 도입됨 GitLab 16.11에서.
  • web_hook_test_api_endpoint_rate_limit라는 플래그로 도입된 특별한 레이트 리밋이 GitLab 17.0에서 기본적으로 활성화되어 있습니다.

지정된 프로젝트에 대해 테스트 프로젝트 웹후크를 트리거합니다.

GitLab 17.0 및 이후 버전에서는 이 엔드포인트에 특별한 레이트 리밋이 있습니다:

  • GitLab 17.0에서는 각 프로젝트 웹후크에 대해 분당 세 번의 요청으로 설정되었습니다.
  • GitLab 17.1에서는 각 프로젝트 및 인증된 사용자에 대해 분당 다섯 번의 요청으로 변경되었습니다.

자체 관리 GitLab 및 GitLab 전용에서 이 제한을 비활성화하려면 관리자가 기능 플래그를 비활성화할 수 있습니다 web_hook_test_api_endpoint_rate_limit라는 이름으로.

POST /projects/:id/hooks/:hook_id/test/:trigger

지원되는 속성:

속성 유형 필수 설명
hook_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 중 하나입니다.

예시 응답:

{"message":"201 Created"}

사용자 정의 헤더 설정 

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

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 프로젝트의 URL 인코딩 경로입니다.
hook_id 정수 예 프로젝트 웹후크의 ID입니다.
key 문자열 예 사용자 정의 헤더의 키입니다.
value 문자열 예 사용자 정의 헤더의 값입니다.

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

사용자 정의 헤더 삭제 

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

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 프로젝트의 URL 인코딩 경로입니다.
hook_id 정수 예 프로젝트 웹후크의 ID입니다.
key 문자열 예 사용자 정의 헤더의 키입니다.

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

URL 변수 설정 

PUT /projects/:id/hooks/:hook_id/url_variables/:key

지원되는 속성:

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

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

URL 변수 삭제 

DELETE /projects/:id/hooks/:hook_id/url_variables/:key

지원되는 속성:

속성 유형 필수 설명
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL이 인코딩된 경로.
hook_id 정수 예 프로젝트 웹훅의 ID.
key 문자열 예 URL 변수의 키.

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