Skip to main content
O controle de versão da API REST já foi feito. Para obter mais informações, confira "Sobre o controle de versão da API".

Pontos de extremidade de API REST para 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 de organização permitem que seu servidor receba cargas úteis HTTP POST sempre que determinados eventos ocorrerem em uma organização. Para obter mais informações, confira "Documentação de webhooks".

Escopos e restrições

Você deve ser proprietário de uma organização ou ter a permissão "Gerenciar webhooks da organização" para usar esses pontos de extremidade. Os tokens OAuth exigem o escopo admin:org_hook para usar esses pontos de extremidade.

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 OAuth apps não podem listar, exibir nem editar webhooks que não criaram.
  • Os usuários não podem listar, exibir ou editar webhooks que foram criados por OAuth apps.

List organization webhooks

Tokens de acesso refinados para "List organization webhooks"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:read

Parâmetros para "List organization webhooks"

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 string Obrigató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). For more information, see "Using pagination in the REST API."

Padrão: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Padrão: 1

Códigos de status de resposta HTTP para "List organization webhooks"

Código de statusDescrição
200

OK

404

Resource not found

Exemplos de código para "List organization webhooks"

Exemplo de solicitação

get/orgs/{org}/hooks
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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:

Tokens de acesso refinados para "Create an organization webhook"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:write

Parâmetros para "Create an organization webhook"

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 string Obrigatório

The organization name. The name is not case sensitive.

Parâmetros do corpo
Nome, Tipo, Descrição
name string Obrigatório

Must be passed as "web".

config object Obrigatório

Key/value pairs to provide settings for this webhook.

Nome, Tipo, Descrição
url string Obrigató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
events array of strings

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

Padrão: ["push"]

active boolean

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 para "Create an organization webhook"

Código de statusDescrição
201

Created

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "Create an organization webhook"

Exemplo de solicitação

post/orgs/{org}/hooks
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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."

Tokens de acesso refinados para "Get an organization webhook"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:read

Parâmetros para "Get an organization webhook"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

Códigos de status de resposta HTTP para "Get an organization webhook"

Código de statusDescrição
200

OK

404

Resource not found

Exemplos de código para "Get an organization webhook"

Exemplo de solicitação

get/orgs/{org}/hooks/{hook_id}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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."

Tokens de acesso refinados para "Update an organization webhook"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:write

Parâmetros para "Update an organization webhook"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

Parâmetros do corpo
Nome, Tipo, Descrição
config object

Key/value pairs to provide settings for this webhook.

Nome, Tipo, Descrição
url string Obrigató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.

events array of strings

Determines what events the hook is triggered for.

Padrão: ["push"]

active boolean

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

Padrão: true

name string

Códigos de status de resposta HTTP para "Update an organization webhook"

Código de statusDescrição
200

OK

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "Update an organization webhook"

Exemplo de solicitação

patch/orgs/{org}/hooks/{hook_id}
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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

Tokens de acesso refinados para "Delete an organization webhook"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:write

Parâmetros para "Delete an organization webhook"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

Códigos de status de resposta HTTP para "Delete an organization webhook"

Código de statusDescrição
204

No Content

404

Resource not found

Exemplos de código para "Delete an organization webhook"

Exemplo de solicitação

delete/orgs/{org}/hooks/{hook_id}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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 ."

OAuth app tokens and personal access tokens (classic) need the admin:org_hook scope to use this endpoint.

Tokens de acesso refinados para "Get a webhook configuration for an organization"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:read

Parâmetros para "Get a webhook configuration for an organization"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

Códigos de status de resposta HTTP para "Get a webhook configuration for an organization"

Código de statusDescrição
200

OK

Exemplos de código para "Get a webhook configuration for an organization"

Exemplo de solicitação

get/orgs/{org}/hooks/{hook_id}/config
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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 ."

OAuth app tokens and personal access tokens (classic) need the admin:org_hook scope to use this endpoint.

Tokens de acesso refinados para "Update a webhook configuration for an organization"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:write

Parâmetros para "Update a webhook configuration for an organization"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

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 para "Update a webhook configuration for an organization"

Código de statusDescrição
200

OK

Exemplos de código para "Update a webhook configuration for an organization"

Exemplo de solicitação

patch/orgs/{org}/hooks/{hook_id}/config
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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.

Tokens de acesso refinados para "List deliveries for an organization webhook"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:read

Parâmetros para "List deliveries for an organization webhook"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

Parâmetros de consulta
Nome, Tipo, Descrição
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

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 para "List deliveries for an organization webhook"

Código de statusDescrição
200

OK

400

Bad Request

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "List deliveries for an organization webhook"

Exemplo de solicitação

get/orgs/{org}/hooks/{hook_id}/deliveries
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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.

Tokens de acesso refinados para "Get a webhook delivery for an organization webhook"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:read

Parâmetros para "Get a webhook delivery for an organization webhook"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

delivery_id integer Obrigatório

Códigos de status de resposta HTTP para "Get a webhook delivery for an organization webhook"

Código de statusDescrição
200

OK

400

Bad Request

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "Get a webhook delivery for an organization webhook"

Exemplo de solicitação

get/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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

Redeliver a delivery for a webhook configured in an organization.

Tokens de acesso refinados para "Redeliver a delivery for an organization webhook"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:write

Parâmetros para "Redeliver a delivery for an organization webhook"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

delivery_id integer Obrigatório

Códigos de status de resposta HTTP para "Redeliver a delivery for an organization webhook"

Código de statusDescrição
202

Accepted

400

Bad Request

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "Redeliver a delivery for an organization webhook"

Exemplo de solicitação

post/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID/deliveries/DELIVERY_ID/attempts

Accepted

Ping an organization webhook

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

Tokens de acesso refinados para "Ping an organization webhook"

Esse ponto de extremidade funciona com os seguintes tipos de token:

O token deve ter os seguintes conjuntos de permissões:

  • organization_hooks:write

Parâmetros para "Ping an organization webhook"

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 string Obrigatório

The organization name. The name is not case sensitive.

hook_id integer Obrigatório

The unique identifier of the hook. You can find this value in the X-GitHub-Hook-ID header of a webhook delivery.

Códigos de status de resposta HTTP para "Ping an organization webhook"

Código de statusDescrição
204

No Content

404

Resource not found

Exemplos de código para "Ping an organization webhook"

Exemplo de solicitação

post/orgs/{org}/hooks/{hook_id}/pings
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/hooks/HOOK_ID/pings

Response

Status: 204