The REST API is now versioned. For more information, see "About API versioning."

조직 웹후크

조직 웹후크 API 정보

조직 웹후크를 사용하면 조직에서 특정 이벤트가 발생할 때마다 HTTP POST 페이로드를 받을 수 있습니다. REST API를 사용하여 리포지토리, 조직 및 앱 웹후크를 관리할 수 있습니다. 웹후크에 대한 웹후크 배달을 나열하거나 외부 앱 또는 서비스에 통합할 수 있는 웹후크에 대한 개별 배달을 가져와서 다시 배달할 수 있습니다. REST API를 사용하여 웹후크의 구성을 변경할 수도 있습니다. 예를 들어 페이로드 URL, 콘텐츠 형식, SSL 확인 및 비밀을 수정할 수 있습니다. 자세한 내용은 다음을 참조하세요.

구독할 수 있는 작업에 대한 자세한 내용은 “GitHub 이벤트 유형”을 참조하세요.

범위 및 제한 사항

조직 웹후크에 대한 모든 작업을 수행하려면 인증된 사용자가 관리되고 있는 조직의 관리자여야 합니다. 또한 OAuth 토큰에는 admin:org_hook 범위가 필요합니다. 자세한 내용은 “OAuth 앱에 대한 범위”를 참조하세요.

웹후크 구성에 있을 수 있는 중요한 데이터를 보호하기 위해 다음 액세스 제어 규칙도 적용합니다.

OAuth 애플리케이션은 OAuth 애플리케이션에서 만들지 않은 웹후크를 나열하거나 보거나 편집할 수 없습니다.
사용자는 OAuth 애플리케이션에서 만든 웹후크를 나열하거나 보거나 편집할 수 없습니다.

웹후크 받기

GitHub가 웹후크 페이로드를 보내려면 인터넷에서 서버에 액세스할 수 있어야 합니다. 또한 HTTPS를 통해 암호화된 페이로드를 보낼 수 있도록 SSL을 사용하는 것이 좋습니다.

더 많은 모범 사례는 가이드를 참조하세요.

웹후크 헤더

GitHub는 이벤트 유형과 페이로드 식별자를 구분하기 위해 여러 HTTP 헤더를 함께 보냅니다. 자세한 내용은 웹후크 헤더를 참조하세요.

List organization webhooks

다음에서 작동 GitHub Apps

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). Default: `30`
`page`integer Page number of the results to fetch. Default: `1`

HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`404`	Resource not found

코드 샘플

get/orgs/{org}/hooks

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks

Response

Status: 200

[
  {
    "id": 1,
    "url": "https://api.github.com/orgs/octocat/hooks/1",
    "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
    "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
    "name": "web",
    "events": [
      "push",
      "pull_request"
    ],
    "active": true,
    "config": {
      "url": "http://example.com",
      "content_type": "json"
    },
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z",
    "type": "Organization"
  }
]

Create an organization webhook

다음에서 작동 GitHub Apps

Here's how you can create a hook that posts payloads in JSON format:

매개 변수

Headers

Name, Type, Description

acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters

Name, Type, Description

orgstringRequired

The organization name. The name is not case sensitive.

Body parameters

Name, Type, Description

namestringRequired

Must be passed as "web".

configobjectRequired

Key/value pairs to provide settings for this webhook. These are defined below.

Properties of config

Name, Type, Description
`url`stringRequired The URL to which the payloads will be delivered.
`content_type`string The media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`.
`secret`string If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value for delivery signature headers.
`insecure_ssl`string or number Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.
`username`string
`password`string

eventsarray of strings

Determines what events the hook is triggered for. Set to ["*"] to receive all possible events.

Default: ["push"]

activeboolean

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

HTTP 응답 상태 코드

상태 코드	설명
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

코드 샘플

post/orgs/{org}/hooks

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks \
  -d '{"name":"web","active":true,"events":["push","pull_request"],"config":{"url":"http://example.com/webhook","content_type":"json"}}'

Response

Status: 201

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Get an organization webhook

다음에서 작동 GitHub Apps

Returns a webhook configured in an organization. To get only the webhook config properties, see "Get a webhook configuration for an organization."

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`404`	Resource not found

코드 샘플

get/orgs/{org}/hooks/{hook_id}

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID

Response

Status: 200

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://api.github.com/orgs/octocat/hooks/1/deliveries",
  "name": "web",
  "events": [
    "push",
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Update an organization webhook

다음에서 작동 GitHub Apps

Updates a webhook configured in an organization. When you update a webhook, the secret will be overwritten. If you previously had a secret set, you must provide the same secret or set a new secret or the secret will be removed. If you are only updating individual webhook config properties, use "Update a webhook configuration for an organization."

매개 변수

Headers

Name, Type, Description

acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters

Name, Type, Description

orgstringRequired

The organization name. The name is not case sensitive.

hook_idintegerRequired

The unique identifier of the hook.

Body parameters

Name, Type, Description

configobject

Key/value pairs to provide settings for this webhook. These are defined below.

Properties of config

Name, Type, Description
`url`stringRequired The URL to which the payloads will be delivered.
`content_type`string The media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`.
`secret`string If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value for delivery signature headers.
`insecure_ssl`string or number Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.

eventsarray of strings

Determines what events the hook is triggered for.

Default: ["push"]

activeboolean

Determines if notifications are sent when the webhook is triggered. Set to true to send notifications.

Default: true

namestring

HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

코드 샘플

patch/orgs/{org}/hooks/{hook_id}

curl \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID \
  -d '{"active":true,"events":["pull_request"]}'

Response

Status: 200

{
  "id": 1,
  "url": "https://api.github.com/orgs/octocat/hooks/1",
  "ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
  "name": "web",
  "events": [
    "pull_request"
  ],
  "active": true,
  "config": {
    "url": "http://example.com",
    "content_type": "json"
  },
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "type": "Organization"
}

Delete an organization webhook

다음에서 작동 GitHub Apps

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

HTTP 응답 상태 코드

상태 코드	설명
`204`	No Content
`404`	Resource not found

코드 샘플

delete/orgs/{org}/hooks/{hook_id}

curl \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID

Response

Status: 204

Get a webhook configuration for an organization

다음에서 작동 GitHub Apps

Returns the webhook configuration for an organization. To get more information about the webhook, including the active state and events, use "Get an organization webhook ."

Access tokens must have the admin:org_hook scope, and GitHub Apps must have the organization_hooks:read permission.

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

HTTP 응답 상태 코드

상태 코드	설명
`200`	OK

코드 샘플

get/orgs/{org}/hooks/{hook_id}/config

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID/config

Response

Status: 200

{
  "content_type": "json",
  "insecure_ssl": "0",
  "secret": "********",
  "url": "https://example.com/webhook"
}

Update a webhook configuration for an organization

다음에서 작동 GitHub Apps

Updates the webhook configuration for an organization. To update more information about the webhook, including the active state and events, use "Update an organization webhook ."

Access tokens must have the admin:org_hook scope, and GitHub Apps must have the organization_hooks:write permission.

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
Body parameters
Name, Type, Description
`url`string The URL to which the payloads will be delivered.
`content_type`string The media type used to serialize the payloads. Supported values include `json` and `form`. The default is `form`.
`secret`string If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value for delivery signature headers.
`insecure_ssl`string or number Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.

HTTP 응답 상태 코드

상태 코드	설명
`200`	OK

코드 샘플

patch/orgs/{org}/hooks/{hook_id}/config

curl \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID/config \
  -d '{"url":"http://example.com/webhook","content_type":"json","insecure_ssl":"0","secret":"********"}'

Response

Status: 200

{
  "content_type": "json",
  "insecure_ssl": "0",
  "secret": "********",
  "url": "https://example.com/webhook"
}

List deliveries for an organization webhook

다음에서 작동 GitHub Apps

Returns a list of webhook deliveries for a webhook configured in an organization.

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). Default: `30`
`cursor`string Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the `link` header for the next and previous page cursors.
`redelivery`boolean

HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

코드 샘플

get/orgs/{org}/hooks/{hook_id}/deliveries

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID/deliveries

Response

Status: 200

[
  {
    "id": 12345678,
    "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
    "delivered_at": "2019-06-03T00:57:16Z",
    "redelivery": false,
    "duration": 0.27,
    "status": "OK",
    "status_code": 200,
    "event": "issues",
    "action": "opened",
    "installation_id": 123,
    "repository_id": 456
  },
  {
    "id": 123456789,
    "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
    "delivered_at": "2019-06-04T00:57:16Z",
    "redelivery": true,
    "duration": 0.28,
    "status": "OK",
    "status_code": 200,
    "event": "issues",
    "action": "opened",
    "installation_id": 123,
    "repository_id": 456
  }
]

Get a webhook delivery for an organization webhook

다음에서 작동 GitHub Apps

Returns a delivery for a webhook configured in an organization.

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
`delivery_id`integerRequired

HTTP 응답 상태 코드

상태 코드	설명
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

코드 샘플

get/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}

curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID

Response

Status: 200

{
  "id": 12345678,
  "guid": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
  "delivered_at": "2019-06-03T00:57:16Z",
  "redelivery": false,
  "duration": 0.27,
  "status": "OK",
  "status_code": 200,
  "event": "issues",
  "action": "opened",
  "installation_id": 123,
  "repository_id": 456,
  "url": "https://www.example.com",
  "request": {
    "headers": {
      "X-GitHub-Delivery": "0b989ba4-242f-11e5-81e1-c7b6966d2516",
      "X-Hub-Signature-256": "sha256=6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "Accept": "*/*",
      "X-GitHub-Hook-ID": "42",
      "User-Agent": "GitHub-Hookshot/b8c71d8",
      "X-GitHub-Event": "issues",
      "X-GitHub-Hook-Installation-Target-ID": "123",
      "X-GitHub-Hook-Installation-Target-Type": "repository",
      "content-type": "application/json",
      "X-Hub-Signature": "sha1=a84d88e7554fc1fa21bcbc4efae3c782a70d2b9d"
    },
    "payload": {
      "action": "opened",
      "issue": {
        "body": "foo"
      },
      "repository": {
        "id": 123
      }
    }
  },
  "response": {
    "headers": {
      "Content-Type": "text/html;charset=utf-8"
    },
    "payload": "ok"
  }
}

Redeliver a delivery for an organization webhook

다음에서 작동 GitHub Apps

Redeliver a delivery for a webhook configured in an organization.

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
`delivery_id`integerRequired

HTTP 응답 상태 코드

상태 코드	설명
`202`	Accepted
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

코드 샘플

post/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts

Accepted

Status: 202

Ping an organization webhook

다음에서 작동 GitHub Apps

This will trigger a ping event to be sent to the hook.

매개 변수

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

HTTP 응답 상태 코드

상태 코드	설명
`204`	No Content
`404`	Resource not found

코드 샘플

post/orgs/{org}/hooks/{hook_id}/pings

curl \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204