Skip to main content
Мы публикуем частые обновления нашей документации, и перевод этой страницы может все еще выполняться. Актуальные сведения см. в документации на английском языке.

Веб-перехватчики организации

Используйте REST API для взаимодействия с веб-перехватчиками в организации.

Сведения о веб-перехватчиках организации

Веб-перехватчики организации позволяют получать полезные данные HTTP-запроса POST всякий раз, когда в организации происходят определенные события. Дополнительные сведения см. в статье Сведения о веб-перехватчиках.

Область действия и ограничения

Любые действия с веб-перехватчиками организации может выполнять только прошедший проверку подлинности пользователь, являющийся администратором управляемой организации. Кроме того, токены OAuth должны иметь область действия admin:org_hook. Дополнительные сведения см. в разделе Области для приложений OAuth.

Чтобы защитить конфиденциальные данные, которые могут присутствовать в конфигурациях веб-перехватчика, также применяются следующие правила управления доступом:

  • Приложения OAuth могут перечислять, просматривать или изменять только те веб-перехватчики, которые были созданы ими.
  • Пользователи не могут перечислять, просматривать или изменять веб-перехватчики, создаваемые приложениями OAuth.

Получение веб-перехватчиков

Для отправки полезных данных веб-перехватчика из GitHub Enterprise Server требуется доступ к серверу через Интернет. Также настоятельно рекомендуется использовать SSL для передачи зашифрованных полезных данных по протоколу HTTPS.

Дополнительные рекомендации см. в нашем руководстве.

Заголовки веб-перехватчиков

GitHub Enterprise Server может отправлять несколько разных заголовков HTTP, которые позволяют различать типы событий и идентификаторы полезных данных. Дополнительные сведения см. разделе Заголовки веб-перехватчика.

List organization webhooks

Работа с GitHub Apps

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

Параметры запроса
Имя, Тип, Описание
per_pageinteger

The number of results per page (max 100).

Значение по умолчанию: 30

pageinteger

Page number of the results to fetch.

Значение по умолчанию: 1

Коды состояния HTTP-ответа

Код состоянияОписание
200

OK

404

Resource not found

Примеры кода

get/orgs/{org}/hooks
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/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:

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

Параметры запроса
Имя, Тип, Описание
namestringОбязательно

Must be passed as "web".

configobjectОбязательно

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

Имя, Тип, Описание
urlstringОбязательно

The URL to which the payloads will be delivered.

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_sslstring 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.

usernamestring
passwordstring
eventsarray of strings

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

Значение по умолчанию: ["push"]

activeboolean

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

Значение по умолчанию: 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>" \ http(s)://HOSTNAME/api/v3/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."

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

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>" \ http(s)://HOSTNAME/api/v3/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."

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

The unique identifier of the hook.

Параметры запроса
Имя, Тип, Описание
configobject

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

Имя, Тип, Описание
urlstringОбязательно

The URL to which the payloads will be delivered.

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_sslstring 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.

Значение по умолчанию: ["push"]

activeboolean

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

Значение по умолчанию: 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>" \ http(s)://HOSTNAME/api/v3/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

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

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>" \ http(s)://HOSTNAME/api/v3/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.

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

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>" \ http(s)://HOSTNAME/api/v3/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.

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

The unique identifier of the hook.

Параметры запроса
Имя, Тип, Описание
urlstring

The URL to which the payloads will be delivered.

content_typestring

The media type used to serialize the payloads. Supported values include json and form. The default is form.

secretstring

If provided, the secret will be used as the key to generate the HMAC hex digest value for delivery signature headers.

insecure_sslstring 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>" \ http(s)://HOSTNAME/api/v3/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.

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

The unique identifier of the hook.

Параметры запроса
Имя, Тип, Описание
per_pageinteger

The number of results per page (max 100).

Значение по умолчанию: 30

cursorstring

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.

redeliveryboolean

Коды состояния 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>" \ http(s)://HOSTNAME/api/v3/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.

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

The unique identifier of the hook.

delivery_idintegerОбязательно

Коды состояния 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>" \ http(s)://HOSTNAME/api/v3/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.

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

The unique identifier of the hook.

delivery_idintegerОбязательно

Коды состояния 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>" \ http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts

Accepted

Ping an organization webhook

Работа с GitHub Apps

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

Параметры

Заголовки
Имя, Тип, Описание
acceptstring

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

Параметры пути
Имя, Тип, Описание
orgstringОбязательно

The organization name. The name is not case sensitive.

hook_idintegerОбязательно

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>" \ http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204