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 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 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.
Receber Webhooks
Para que GitHub 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 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
Parâmetros para "List organization webhooks"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
Nome, Type, Descrição |
---|
per_page integer The number of results per page (max 100). Padrão: |
page integer Page number of the results to fetch. Padrão: |
Códigos de status de resposta HTTP para "List organization webhooks"
Código de status | Descrição |
---|---|
200 | OK |
404 | Resource not found |
Exemplos de código para "List organization webhooks"
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:
Parâmetros para "Create an organization webhook"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
Nome, Type, Descrição | |||||||
---|---|---|---|---|---|---|---|
name string ObrigatórioMust be passed as "web". | |||||||
config object ObrigatórioKey/value pairs to provide settings for this webhook. | |||||||
Properties of |
Nome, Type, Descrição |
---|
url string ObrigatórioThe 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 |
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 status | Descriçã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"
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."
Parâmetros para "Get an organization webhook"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
Códigos de status de resposta HTTP para "Get an organization webhook"
Código de status | Descrição |
---|---|
200 | OK |
404 | Resource not found |
Exemplos de código para "Get an organization webhook"
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."
Parâmetros para "Update an organization webhook"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
Nome, Type, Descrição | |||||
---|---|---|---|---|---|
config object Key/value pairs to provide settings for this webhook. | |||||
Properties of |
Nome, Type, Descrição |
---|
url string ObrigatórioThe 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 |
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 status | Descriçã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"
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
Parâmetros para "Delete an organization webhook"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
Códigos de status de resposta HTTP para "Delete an organization webhook"
Código de status | Descrição |
---|---|
204 | No Content |
404 | Resource not found |
Exemplos de código para "Delete an organization webhook"
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 ."
Access tokens must have the admin:org_hook
scope, and GitHub Apps must have the organization_hooks:read
permission.
Parâmetros para "Get a webhook configuration for an organization"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
Códigos de status de resposta HTTP para "Get a webhook configuration for an organization"
Código de status | Descrição |
---|---|
200 | OK |
Exemplos de código para "Get a webhook configuration for an organization"
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 ."
Access tokens must have the admin:org_hook
scope, and GitHub Apps must have the organization_hooks:write
permission.
Parâmetros para "Update a webhook configuration for an organization"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
Nome, Type, 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 |
secret string If provided, the |
insecure_ssl string or number Determines whether the SSL certificate of the host for |
Códigos de status de resposta HTTP para "Update a webhook configuration for an organization"
Código de status | Descrição |
---|---|
200 | OK |
Exemplos de código para "Update a webhook configuration for an organization"
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.
Parâmetros para "List deliveries for an organization webhook"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
Nome, Type, Descrição |
---|
per_page integer The number of results per page (max 100). Padrão: |
cursor string Used for pagination: the starting delivery from which the page of deliveries is fetched. Refer to the |
redelivery boolean |
Códigos de status de resposta HTTP para "List deliveries for an organization webhook"
Código de status | Descriçã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"
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.
Parâmetros para "Get a webhook delivery for an organization webhook"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
delivery_id integer Obrigatório |
Códigos de status de resposta HTTP para "Get a webhook delivery for an organization webhook"
Código de status | Descriçã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"
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.
Parâmetros para "Redeliver a delivery for an organization webhook"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
delivery_id integer Obrigatório |
Códigos de status de resposta HTTP para "Redeliver a delivery for an organization webhook"
Código de status | Descriçã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"
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
Status: 202
Ping an organization webhook
This will trigger a ping event to be sent to the hook.
Parâmetros para "Ping an organization webhook"
Nome, Type, Descrição |
---|
accept string Setting to |
Nome, Type, Descrição |
---|
org string ObrigatórioThe organization name. The name is not case sensitive. |
hook_id integer ObrigatórioThe unique identifier of the hook. You can find this value in the |
Códigos de status de resposta HTTP para "Ping an organization webhook"
Código de status | Descrição |
---|---|
204 | No Content |
404 | Resource not found |
Exemplos de código para "Ping an organization webhook"
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