Webhooks de organización
Usa la API REST para interactuar con webhooks en una organización.
Acerca de los webhooks de la organización
Los webhooks de organización permiten recibir cargas útiles de HTTP POST
cuando se producen determinados eventos en una organización. Para obtener más información, vea «Acerca de webhooks».
Ámbitos y restricciones
Todas las acciones en contra de los webhooks de una organización requieren que el usuario autenticado sea un administrador de la organización que se está administrando. Además, los tokens de OAuth necesitan el ámbito admin:org_hook
. Para obtener más información, vea «Scopes for OAuth Apps».
Para porteger los datos sensibles que pueden encontrarse en las configuraciones de los webhooks, también imponemos las siguientes reglas de control de accesos:
- Las aplicaciones de OAuth no pueden listar, ver o editar los webhooks que no crearon ellas mismas.
- Los usuarios no pueden listar, ver o editar los webhooks que crearon las aplicaciones de OAuth.
Recibir Webhooks
Para que GitHub AE envíe cargas útiles de webhooks, se necesita que se pueda acceder a tu servidor desde la internet. También sugerimos ampliamente utilizar SSL para que podamos enviar cargas útiles cifradas a través de HTTPS.
Para obtener más procedimientos recomendados, vea nuestra guía.
Encabezados de Webhook
GitHub AE enviará varios encabezados de HTTP para diferenciar los tipos de eventos y los identificadores de las cargas útiles. Vea encabezados de webhook para más información.
List organization webhooks
Parameters for "List organization webhooks"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
Query parameters |
Name, Type, Description |
per_page integerThe number of results per page (max 100). Default: |
page integerPage number of the results to fetch. Default: |
HTTP response status codes for "List organization webhooks"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples for "List organization webhooks"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://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
Here's how you can create a hook that posts payloads in JSON format:
Parameters for "Create an organization webhook"
Headers | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Name, Type, Description | ||||||||||
accept stringSetting to | ||||||||||
Path parameters | ||||||||||
Name, Type, Description | ||||||||||
org stringRequiredThe organization name. The name is not case sensitive. | ||||||||||
Body parameters | ||||||||||
Name, Type, Description | ||||||||||
name stringRequiredMust be passed as "web". | ||||||||||
config objectRequiredKey/value pairs to provide settings for this webhook. These are defined below. | ||||||||||
Properties of |
Name, Type, Description |
---|
url stringRequiredThe URL to which the payloads will be delivered. |
content_type stringThe media type used to serialize the payloads. Supported values include |
secret stringIf provided, the |
insecure_ssl string or numberDetermines whether the SSL certificate of the host for |
username string |
password string |
events
array of stringsDetermines what events the hook is triggered for. Set to ["*"]
to receive all possible events.
Default: ["push"]
active
booleanDetermines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
Default: true
HTTP response status codes for "Create an organization webhook"
Status code | Description |
---|---|
201 | Created |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Create an organization webhook"
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://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
Returns a webhook configured in an organization. To get only the webhook config
properties, see "Get a webhook configuration for an organization."
Parameters for "Get an organization webhook"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP response status codes for "Get an organization webhook"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
Code samples for "Get an organization webhook"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://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
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."
Parameters for "Update an organization webhook"
Headers | ||||||||
---|---|---|---|---|---|---|---|---|
Name, Type, Description | ||||||||
accept stringSetting to | ||||||||
Path parameters | ||||||||
Name, Type, Description | ||||||||
org stringRequiredThe organization name. The name is not case sensitive. | ||||||||
hook_id integerRequiredThe unique identifier of the hook. | ||||||||
Body parameters | ||||||||
Name, Type, Description | ||||||||
config objectKey/value pairs to provide settings for this webhook. These are defined below. | ||||||||
Properties of |
Name, Type, Description |
---|
url stringRequiredThe URL to which the payloads will be delivered. |
content_type stringThe media type used to serialize the payloads. Supported values include |
secret stringIf provided, the |
insecure_ssl string or numberDetermines whether the SSL certificate of the host for |
events
array of stringsDetermines what events the hook is triggered for.
Default: ["push"]
active
booleanDetermines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
Default: true
name
stringHTTP response status codes for "Update an organization webhook"
Status code | Description |
---|---|
200 | OK |
404 | Resource not found |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Update an organization webhook"
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://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
Parameters for "Delete an organization webhook"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP response status codes for "Delete an organization webhook"
Status code | Description |
---|---|
204 | No Content |
404 | Resource not found |
Code samples for "Delete an organization webhook"
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID
Response
Status: 204
Get a webhook configuration for an organization
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.
Parameters for "Get a webhook configuration for an organization"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP response status codes for "Get a webhook configuration for an organization"
Status code | Description |
---|---|
200 | OK |
Code samples for "Get a webhook configuration for an organization"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://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
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.
Parameters for "Update a webhook configuration for an organization"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
Body parameters |
Name, Type, Description |
url stringThe URL to which the payloads will be delivered. |
content_type stringThe media type used to serialize the payloads. Supported values include |
secret stringIf provided, the |
insecure_ssl string or numberDetermines whether the SSL certificate of the host for |
HTTP response status codes for "Update a webhook configuration for an organization"
Status code | Description |
---|---|
200 | OK |
Code samples for "Update a webhook configuration for an organization"
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://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
Returns a list of webhook deliveries for a webhook configured in an organization.
Parameters for "List deliveries for an organization webhook"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
Query parameters |
Name, Type, Description |
per_page integerThe number of results per page (max 100). Default: |
cursor stringUsed for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
redelivery boolean |
HTTP response status codes for "List deliveries for an organization webhook"
Status code | Description |
---|---|
200 | OK |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "List deliveries for an organization webhook"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://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
Returns a delivery for a webhook configured in an organization.
Parameters for "Get a webhook delivery for an organization webhook"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
delivery_id integerRequired |
HTTP response status codes for "Get a webhook delivery for an organization webhook"
Status code | Description |
---|---|
200 | OK |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Get a webhook delivery for an organization webhook"
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://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"
},
"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
Redeliver a delivery for a webhook configured in an organization.
Parameters for "Redeliver a delivery for an organization webhook"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
delivery_id integerRequired |
HTTP response status codes for "Redeliver a delivery for an organization webhook"
Status code | Description |
---|---|
202 | Accepted |
400 | Bad Request |
422 | Validation failed, or the endpoint has been spammed. |
Code samples for "Redeliver a delivery for an organization webhook"
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts
Accepted
Status: 202
Ping an organization webhook
This will trigger a ping event to be sent to the hook.
Parameters for "Ping an organization webhook"
Headers |
---|
Name, Type, Description |
accept stringSetting to |
Path parameters |
Name, Type, Description |
org stringRequiredThe organization name. The name is not case sensitive. |
hook_id integerRequiredThe unique identifier of the hook. |
HTTP response status codes for "Ping an organization webhook"
Status code | Description |
---|---|
204 | No Content |
404 | Resource not found |
Code samples for "Ping an organization webhook"
curl -L \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/pings
Response
Status: 204