Los webhooks de repositorio te permiten recibir cargas útiles de POST
por HTTP cuando ciertos eventos suceden en un repositorio. Las API de REST de los webhooks te permiten administrar webhooks de repositorio, organización y aplicación.. También puedes utilizar la API de REST para cambiar la configuración del webhook. Por ejemplo, puedes modificar la URL de la carga útil, el tipo de contenido, la verificación de SSL, y el secreto. Para obtener más información, consulta:
- API de REST para los webhooks de los repositorios
- API de REST de webhooks de organización
- GitHub App API de REST de Webhooks
Si te gustaría configurar un solo webhook para recibir eventos de todos los repositorios de tu organización, consulta nuestra documentación de la API para los Webhooks de una Organización.
Adicionalmente a la API de REST, GitHub también puede servir como un punto de PubSubHubbub para los repositorios.
Webhooks de repositorio
get /repos/{owner}/{repo}/hooks
Parámetros
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
per_page |
integer | query |
Results per page (max 100) Default:30 |
page |
integer | query |
Page number of the results to fetch. Default:1 |
Ejemplos de código
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/hooks', {
owner: 'octocat',
repo: 'hello-world'
})
Response
Status: 200 OK
[
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
]
Resource not found
Status: 404 Not Found
Notes
Create a repository webhook
Repositories can have multiple webhooks installed. Each webhook should have a unique config
. Multiple webhooks can
share the same config
as long as those webhooks do not have any events
that overlap.
post /repos/{owner}/{repo}/hooks
Parámetros
Name | Type | In | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
Setting to
|
||||||||||||||
owner |
string | path | |||||||||||||||
repo |
string | path | |||||||||||||||
name |
string | body |
Use |
||||||||||||||
config |
object | body |
Key/value pairs to provide settings for this webhook. These are defined below. |
||||||||||||||
Properties of the
|
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 |
secret (string)
|
If provided, the |
insecure_ssl (string or number)
|
Determines whether the SSL certificate of the host for |
token (string)
|
|
digest (string)
|
events
Determines what events the hook is triggered for.
Default:push
active
Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
true
Ejemplos de código
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks \
-d '{"name":"name"}'
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks', {
owner: 'octocat',
repo: 'hello-world',
name: 'name'
})
Response
Status: 201 Created
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Forbidden
Status: 403 Forbidden
Resource not found
Status: 404 Not Found
Validation failed
Status: 422 Unprocessable Entity
Notes
Get a repository webhook
Returns a webhook configured in a repository. To get only the webhook config
properties, see "Get a webhook configuration for a repository."
get /repos/{owner}/{repo}/hooks/{hook_id}
Parámetros
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Ejemplos de código
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 200 OK
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Resource not found
Status: 404 Not Found
Notes
Update a repository webhook
Updates a webhook configured in a repository. 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 a repository."
patch /repos/{owner}/{repo}/hooks/{hook_id}
Parámetros
Name | Type | In | Description | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
accept |
string | header |
Setting to
|
||||||||||||||
owner |
string | path | |||||||||||||||
repo |
string | path | |||||||||||||||
hook_id |
integer | path | |||||||||||||||
config |
object | body |
Key/value pairs to provide settings for this webhook. These are defined below. |
||||||||||||||
Properties of the
|
Name (Type) | Description |
---|---|
url (string)
|
Required. The URL to which the payloads will be delivered. |
content_type (string)
|
The media type used to serialize the payloads. Supported values include |
secret (string)
|
If provided, the |
insecure_ssl (string or number)
|
Determines whether the SSL certificate of the host for |
address (string)
|
|
room (string)
|
events
Determines what events the hook is triggered for. This replaces the entire array of events.
Default:push
add_events
Determines a list of events to be added to the list of events that the Hook triggers for.
remove_events
Determines a list of events to be removed from the list of events that the Hook triggers for.
active
Determines if notifications are sent when the webhook is triggered. Set to true
to send notifications.
true
Ejemplos de código
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42 \
-d '{"config":{"url":"url","content_type":"content_type","secret":"secret","insecure_ssl":"insecure_ssl","address":"address","room":"room"}}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42,
config: {
url: 'url',
content_type: 'content_type',
secret: 'secret',
insecure_ssl: 'insecure_ssl',
address: 'address',
room: 'room'
}
})
Response
Status: 200 OK
{
"type": "Repository",
"id": 12345678,
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"content_type": "json",
"insecure_ssl": "0",
"url": "https://example.com/webhook"
},
"updated_at": "2019-06-03T00:57:16Z",
"created_at": "2019-06-03T00:57:16Z",
"url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
"test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
"ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
"last_response": {
"code": null,
"status": "unused",
"message": null
}
}
Resource not found
Status: 404 Not Found
Validation failed
Status: 422 Unprocessable Entity
Notes
delete /repos/{owner}/{repo}/hooks/{hook_id}
Parámetros
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Ejemplos de código
Shell
curl \
-X DELETE \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42
JavaScript (@octokit/core.js)
await octokit.request('DELETE /repos/{owner}/{repo}/hooks/{hook_id}', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 204 No Content
Resource not found
Status: 404 Not Found
Notes
Ping a repository webhook
This will trigger a ping event to be sent to the hook.
post /repos/{owner}/{repo}/hooks/{hook_id}/pings
Parámetros
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Ejemplos de código
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42/pings
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/pings', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 204 No Content
Resource not found
Status: 404 Not Found
Notes
Test the push repository webhook
This will trigger the hook with the latest push to the current repository if the hook is subscribed to push
events. If the hook is not subscribed to push
events, the server will respond with 204 but no test POST will be generated.
Note: Previously /repos/:owner/:repo/hooks/:hook_id/test
post /repos/{owner}/{repo}/hooks/{hook_id}/tests
Parámetros
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Ejemplos de código
Shell
curl \
-X POST \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42/tests
JavaScript (@octokit/core.js)
await octokit.request('POST /repos/{owner}/{repo}/hooks/{hook_id}/tests', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 204 No Content
Resource not found
Status: 404 Not Found
Notes
Repository webhook configuration
Get a webhook configuration for a repository
Returns the webhook configuration for a repository. To get more information about the webhook, including the active
state and events
, use "Get a repository webhook."
Access tokens must have the read:repo_hook
or repo
scope, and GitHub Apps must have the repository_hooks:read
permission.
get /repos/{owner}/{repo}/hooks/{hook_id}/config
Parámetros
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path |
Ejemplos de código
Shell
curl \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42/config
JavaScript (@octokit/core.js)
await octokit.request('GET /repos/{owner}/{repo}/hooks/{hook_id}/config', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42
})
Response
Status: 200 OK
{
"content_type": "json",
"insecure_ssl": "0",
"secret": "********",
"url": "https://example.com/webhook"
}
Notes
Update a webhook configuration for a repository
Updates the webhook configuration for a repository. To update more information about the webhook, including the active
state and events
, use "Update a repository webhook."
Access tokens must have the write:repo_hook
or repo
scope, and GitHub Apps must have the repository_hooks:write
permission.
patch /repos/{owner}/{repo}/hooks/{hook_id}/config
Parámetros
Name | Type | In | Description |
---|---|---|---|
accept |
string | header |
Setting to
|
owner |
string | path | |
repo |
string | path | |
hook_id |
integer | path | |
url |
string | body |
The URL to which the payloads will be delivered. |
content_type |
string | body |
The media type used to serialize the payloads. Supported values include |
secret |
string | body |
If provided, the |
insecure_ssl |
string or number | body |
Determines whether the SSL certificate of the host for |
Ejemplos de código
Shell
curl \
-X PATCH \
-H "Accept: application/vnd.github.v3+json" \
http(s)://{hostname}/api/v3/repos/octocat/hello-world/hooks/42/config \
-d '{"url":"url"}'
JavaScript (@octokit/core.js)
await octokit.request('PATCH /repos/{owner}/{repo}/hooks/{hook_id}/config', {
owner: 'octocat',
repo: 'hello-world',
hook_id: 42,
url: 'url'
})
Response
Status: 200 OK
{
"content_type": "json",
"insecure_ssl": "0",
"secret": "********",
"url": "https://example.com/webhook"
}
Notes
Repository webhook deliveries
Recibir Webhooks
Para que GitHub Enterprise Server 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.
Encabezados de Webhook
GitHub Enterprise Server enviará varios encabezados de HTTP para diferenciar los tipos de eventos y los identificadores de las cargas útiles. Consulta la sección de encabezados de webhook para encontrar más detalles.
PubSubHubbub
GitHub también puede fungir como un centro de PubSubHubbub para todos los repositorios. PSHB es un proptocolo simple de publicación/suscripción que permite a los servidores registrarse para recibir actualizaciones de cuándo se actualiza un tema. Las actualizaciones se mandan con una solicitud HTTP de tipo POST a una URL de rellamado. Las URL de tema para las cargas a un repositorio de GitHub están en este formato:
https://github.com/{owner}/{repo}/events/{event}
El veneto puede ser cualquier evento de webhook disponible. Para obtener más información, consulta la sección "eventos y cargas útiles de los webhooks".
Formato de respuesta
El formato predeterminado es lo que deberían esperar los ganchos de post-recepción: Un cuerpo de JSON que se envía como un parámetro de payload
en un POST. También puedes especificar si quieres recibir el cuerpo en JSON sin procesar, ya sea un encabezado de Accept
o una extensión .json
.
Accept: application/json
https://github.com/{owner}/{repo}/events/push.json
URL de Rellamado
Las URL de rellamado puede utilizar el protocolo http://
.
# Send updates to postbin.org
http://postbin.org/123
Suscribirse
La terminal de PubSubHubbub de GitHub es: http(s)://[hostname]/api/v3/hub
. Una solicitud exitosa con curl se vería así:
curl -u "user" -i \
http(s)://[hostname]/api/v3/hub \
-F "hub.mode=subscribe" \
-F "hub.topic=https://github.com/{owner}/{repo}/events/push" \
-F "hub.callback=http://postbin.org/123"
Las solicitudes de PubSubHubbub pueden enviarse varias veces. Si el gancho ya existe, se modificará de acuerdo con la solicitud.
Parámetros
Nombre | Tipo | Descripción |
---|---|---|
hub.mode | secuencia | Requerido. Ya sea subscribe o unsubscribe . |
hub.topic | secuencia | Requerido. La URI del repositorio de GitHub al cual suscribirse. La ruta debe estar en el formato /{owner}/{repo}/events/{event} . |
hub.callback | secuencia | La URI para recibir las actualizaciones del tema. |
hub.secret | secuencia | Una llave de secreto compartido que genera una firma de hash del contenido saliente del cuerpo. Puedes verificar si una subida vino de GitHub comparando el cuerpo de la solicitud sin procesar con el contenido de los encabezados de la X-Hub-Signature o X-Hub-Signature-256 . Puedes ver la documentación de PubSubHubbub para obtener más detalles. |