Webhooks da organização

Use a API REST para interagir com webhooks em uma organização.

Sobre os webhooks de uma organização

Os webhooks da organização permitem que você receba conteúdo POST HTTP sempre que determinados eventos ocorrerem em uma organização. Para obter mais informações, confira "Sobre os webhooks".

Escopos e restrições

Todas as ações contra webhooks da organização exigem que o usuário autenticado seja um administrador da organização que está sendo gerenciada. Além disso, os tokens OAuth exigem o escopo admin:org_hook. Para obter mais informações, confira "Escopos para Aplicativos OAuth".

Para proteger dados sensíveis que podem estar presentes nas configurações do webhook, também aplicamos as seguintes regras de controle de acesso:

Os aplicativos OAuth não podem listar, visualizar ou editar webhooks que não criaram.
Os usuários não podem listar, visualizar ou editar webhooks que foram criados por aplicativos OAuth.

Receber Webhooks

Para que GitHub Enterprise Server envie cargas de webhook, seu servidor deve ser acessível pela internet. É altamente recomendável o uso de SSL para que possamos enviar cargas criptografadas por HTTPS.

Para ver as melhores práticas, confira nosso guia.

Cabeçalhos de webhook

GitHub Enterprise Server enviará ao longo de vários cabeçalhos de HTTP para diferenciar entre tipos de evento e identificadores de carga. Confira Cabeçalhos de webhook para ver detalhes.

List organization webhooks

Funciona com GitHub Apps

Parâmetros

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
Parâmetros de consulta
Nome, Tipo, Descrição
`per_page`integer The number of results per page (max 100). Padrão: `30`
`page`integer Page number of the results to fetch. Padrão: `1`

Códigos de status de resposta HTTP

Código de status	Descrição
`200`	OK
`404`	Resource not found

Exemplos de código

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

Funciona com GitHub Apps

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

Parâmetros

Cabeçalhos

Nome, Tipo, Descrição

acceptstring

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

Parâmetros de caminho

Nome, Tipo, Descrição

orgstringObrigatório

The organization name. The name is not case sensitive.

Parâmetros do corpo

Nome, Tipo, Descrição

namestringObrigatório

Must be passed as "web".

configobjectObrigatório

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

Properties of config

Nome, Tipo, Descrição
`url`stringObrigatório 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.

Padrão: ["push"]

activeboolean

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

Padrão: true

Códigos de status de resposta HTTP

Código de status	Descrição
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Exemplos de código

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

Funciona com 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

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
`hook_id`integerObrigatório The unique identifier of the hook.

Códigos de status de resposta HTTP

Código de status	Descrição
`200`	OK
`404`	Resource not found

Exemplos de código

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

Funciona com 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

Cabeçalhos

Nome, Tipo, Descrição

acceptstring

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

Parâmetros de caminho

Nome, Tipo, Descrição

orgstringObrigatório

The organization name. The name is not case sensitive.

hook_idintegerObrigatório

The unique identifier of the hook.

Parâmetros do corpo

Nome, Tipo, Descrição

configobject

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

Properties of config

Nome, Tipo, Descrição
`url`stringObrigatório 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.

Padrão: ["push"]

activeboolean

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

Padrão: true

namestring

Códigos de status de resposta HTTP

Código de status	Descrição
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Exemplos de código

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

Funciona com GitHub Apps

Parâmetros

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
`hook_id`integerObrigatório The unique identifier of the hook.

Códigos de status de resposta HTTP

Código de status	Descrição
`204`	No Content
`404`	Resource not found

Exemplos de código

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

Funciona com 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

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
`hook_id`integerObrigatório The unique identifier of the hook.

Códigos de status de resposta HTTP

Código de status	Descrição
`200`	OK

Exemplos de código

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

Funciona com 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

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
`hook_id`integerObrigatório The unique identifier of the hook.
Parâmetros do corpo
Nome, Tipo, Descrição
`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.

Códigos de status de resposta HTTP

Código de status	Descrição
`200`	OK

Exemplos de código

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

Funciona com GitHub Apps

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

Parâmetros

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
`hook_id`integerObrigatório The unique identifier of the hook.
Parâmetros de consulta
Nome, Tipo, Descrição
`per_page`integer The number of results per page (max 100). Padrão: `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

Códigos de status de resposta HTTP

Código de status	Descrição
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Exemplos de código

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

Funciona com GitHub Apps

Returns a delivery for a webhook configured in an organization.

Parâmetros

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
`hook_id`integerObrigatório The unique identifier of the hook.
`delivery_id`integerObrigatório

Códigos de status de resposta HTTP

Código de status	Descrição
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Exemplos de código

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

Funciona com GitHub Apps

Redeliver a delivery for a webhook configured in an organization.

Parâmetros

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
`hook_id`integerObrigatório The unique identifier of the hook.
`delivery_id`integerObrigatório

Códigos de status de resposta HTTP

Código de status	Descrição
`202`	Accepted
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Exemplos de código

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

Status: 202

Ping an organization webhook

Funciona com GitHub Apps

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

Parâmetros

Cabeçalhos
Nome, Tipo, Descrição
`accept`string Setting to `application/vnd.github+json` is recommended.
Parâmetros de caminho
Nome, Tipo, Descrição
`org`stringObrigatório The organization name. The name is not case sensitive.
`hook_id`integerObrigatório The unique identifier of the hook.

Códigos de status de resposta HTTP

Código de status	Descrição
`204`	No Content
`404`	Resource not found

Exemplos de código

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