Webhooks de organización

About the Organization webhooks API

Los webhooks de las organizaciones te permiten recibir cargas útiles de POST por HTTP cuando ciertos eventos suceden en una organización. 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:

Para obtener más información sobre las acciones a las cuales te puedes suscribir, consulta los "tipos de eventos de GitHub".

Scopes and restrictions

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. Adicionalmente, los tokens de OAuth requieren el alcance admin:org_hook. Par aobtener más información, consulta la sección "Alcances para las Apps de OAuth".

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

Para encontrar más de las mejores prácticas, consulta nuestra guía.

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.

List organization webhooks

Funciona con GitHub Apps

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`org`stringRequerido The organization name. The name is not case sensitive.
Parámetros de consulta
Nombre, Tipo, Descripción
`per_page`integer The number of results per page (max 100). Predeterminado: `30`
`page`integer Page number of the results to fetch. Predeterminado: `1`

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK
`404`	Resource not found

Ejemplos de código

get/orgs/{org}/hooks

curl \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <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",
    "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

Funciona con GitHub Apps

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

Parámetros

Encabezados

Nombre, Tipo, Descripción

acceptstring

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

Parámetros de ruta

Nombre, Tipo, Descripción

orgstringRequerido

The organization name. The name is not case sensitive.

Parámetros de cuerpo

Nombre, Tipo, Descripción

namestringRequerido

Must be passed as "web".

configobjectRequerido

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

Properties of theconfigobject

Nombre, Tipo, Descripción
`url`stringRequerido 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 or 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.

Predeterminado: push

activeboolean

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

Predeterminado: true

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`201`	Created
`404`	Resource not found
`422`	Validation failed

Ejemplos de código

post/orgs/{org}/hooks

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <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",
  "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

Funciona con GitHub Apps

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

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`org`stringRequerido The organization name. The name is not case sensitive.
`hook_id`integerRequerido The unique identifier of the hook.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK
`404`	Resource not found

Ejemplos de código

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

curl \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <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",
  "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

Funciona con 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."

Parámetros

Encabezados

Nombre, Tipo, Descripción

acceptstring

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

Parámetros de ruta

Nombre, Tipo, Descripción

orgstringRequerido

The organization name. The name is not case sensitive.

hook_idintegerRequerido

The unique identifier of the hook.

Parámetros de cuerpo

Nombre, Tipo, Descripción

configobject

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

Properties of theconfigobject

Nombre, Tipo, Descripción
`url`stringRequerido 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 or 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.

Predeterminado: push

activeboolean

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

Predeterminado: true

namestring

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK
`404`	Resource not found
`422`	Validation failed

Ejemplos de código

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

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <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",
  "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

Funciona con GitHub Apps

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`org`stringRequerido The organization name. The name is not case sensitive.
`hook_id`integerRequerido The unique identifier of the hook.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`204`	No Content
`404`	Resource not found

Ejemplos de código

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

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID

Response

Status: 204

Get a webhook configuration for an organization

Funciona con 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.

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`org`stringRequerido The organization name. The name is not case sensitive.
`hook_id`integerRequerido The unique identifier of the hook.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK

Ejemplos de código

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

curl \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <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

Funciona con 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.

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`org`stringRequerido The organization name. The name is not case sensitive.
`hook_id`integerRequerido The unique identifier of the hook.
Parámetros de cuerpo
Nombre, Tipo, Descripción
`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 or 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.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK

Ejemplos de código

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

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <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"
}

Ping an organization webhook

Funciona con GitHub Apps

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

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`org`stringRequerido The organization name. The name is not case sensitive.
`hook_id`integerRequerido The unique identifier of the hook.

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`204`	No Content
`404`	Resource not found

Ejemplos de código

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

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204