Points de terminaison d’API REST pour les webhooks de l’organisation

À propos des webhooks d’organisation

Les webhooks d'organisation permettent à votre serveur de recevoir des charges utiles HTTP POST chaque fois que certains événements se produisent dans une organisation. Pour plus d’informations, consultez « Documentation sur les webhooks ».

Étendues et restrictions

Vous devez être un propriétaire d'organisation pour utiliser ces points de terminaison. Les jetons OAuth nécessitent l'étendue admin:org_hook pour utiliser ces points de terminaison.

Pour protéger les données sensibles qui peuvent être présentes dans des configurations de webhook, nous appliquons également les règles de contrôle d’accès suivantes :

OAuth apps ne peuvent pas lister, visualiser ou modifier les webhooks qu’ils n’ont pas créés.
Les utilisateurs ne peuvent pas répertorier, afficher ni modifier des webhooks créés par des OAuth apps.

List organization webhooks

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « List organization webhooks »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.

Paramètres de requête
Nom, Type, Description
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

Codes d’état de la réponse HTTP pour « List organization webhooks »

Code d’état	Description
`200`	OK
`404`	Resource not found

Exemples de code pour « List organization webhooks »

Exemple de requête

get/orgs/{org}/hooks

curl -L \
  -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://HOSTNAME/orgs/octocat/hooks/1",
    "ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
    "deliveries_url": "https://HOSTNAME/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

Create a hook that posts payloads in JSON format.

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Create an organization webhook »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.

Nom, Type, Description

name string Obligatoire

Must be passed as "web".

config object Obligatoire

Key/value pairs to provide settings for this webhook.

Properties of config

Nom, Type, Description
`url` string Obligatoire 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.

Default: ["push"]

active boolean

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

Default: true

Codes d’état de la réponse HTTP pour « Create an organization webhook »

Code d’état	Description
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Exemples de code pour « Create an organization webhook »

Exemple de requête

post/orgs/{org}/hooks

curl -L \
  -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://HOSTNAME/orgs/octocat/hooks/1",
  "ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://HOSTNAME/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.

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Get an organization webhook »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

Codes d’état de la réponse HTTP pour « Get an organization webhook »

Code d’état	Description
`200`	OK
`404`	Resource not found

Exemples de code pour « Get an organization webhook »

Exemple de requête

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

curl -L \
  -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://HOSTNAME/orgs/octocat/hooks/1",
  "ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://HOSTNAME/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".

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Update an organization webhook »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

Nom, Type, Description

config object

Key/value pairs to provide settings for this webhook.

Properties of config

Nom, Type, Description
`url` string Obligatoire 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.

Default: ["push"]

active boolean

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

Default: true

name string

Codes d’état de la réponse HTTP pour « Update an organization webhook »

Code d’état	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Exemples de code pour « Update an organization webhook »

Exemple de requête

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

curl -L \
  -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://HOSTNAME/orgs/octocat/hooks/1",
  "ping_url": "https://HOSTNAME/orgs/octocat/hooks/1/pings",
  "deliveries_url": "https://HOSTNAME/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

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Delete an organization webhook »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

Codes d’état de la réponse HTTP pour « Delete an organization webhook »

Code d’état	Description
`204`	No Content
`404`	Resource not found

Exemples de code pour « Delete an organization webhook »

Exemple de requête

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

curl -L \
  -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

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

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Get a webhook configuration for an organization »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

Codes d’état de la réponse HTTP pour « Get a webhook configuration for an organization »

Code d’état	Description
`200`	OK

Exemples de code pour « Get a webhook configuration for an organization »

Exemple de requête

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

curl -L \
  -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

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

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Update a webhook configuration for an organization »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

Paramètres du corps
Nom, 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 `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.

Codes d’état de la réponse HTTP pour « Update a webhook configuration for an organization »

Code d’état	Description
`200`	OK

Exemples de code pour « Update a webhook configuration for an organization »

Exemple de requête

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

curl -L \
  -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

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

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « List deliveries for an organization webhook »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

Paramètres de requête
Nom, Type, Description
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `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

Codes d’état de la réponse HTTP pour « List deliveries for an organization webhook »

Code d’état	Description
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Exemples de code pour « List deliveries for an organization webhook »

Exemple de requête

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

curl -L \
  -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

Returns a delivery for a webhook configured in an organization.

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Get a webhook delivery for an organization webhook »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire 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 Obligatoire

Codes d’état de la réponse HTTP pour « Get a webhook delivery for an organization webhook »

Code d’état	Description
`200`	OK
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Exemples de code pour « Get a webhook delivery for an organization webhook »

Exemple de requête

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

curl -L \
  -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

Redeliver a delivery for a webhook configured in an organization.

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Redeliver a delivery for an organization webhook »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire 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 Obligatoire

Codes d’état de la réponse HTTP pour « Redeliver a delivery for an organization webhook »

Code d’état	Description
`202`	Accepted
`400`	Bad Request
`422`	Validation failed, or the endpoint has been spammed.

Exemples de code pour « Redeliver a delivery for an organization webhook »

Exemple de requête

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>" \
  http(s)://HOSTNAME/api/v3/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.

You must be an organization owner to use this endpoint.

OAuth app tokens and personal access tokens (classic) need admin:org_hook scope. OAuth apps cannot list, view, or edit webhooks that they did not create and users cannot list, view, or edit webhooks that were created by OAuth apps.

Paramètres pour « Ping an organization webhook »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`org` string Obligatoire The organization name. The name is not case sensitive.
`hook_id` integer Obligatoire The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

Codes d’état de la réponse HTTP pour « Ping an organization webhook »

Code d’état	Description
`204`	No Content
`404`	Resource not found

Exemples de code pour « Ping an organization webhook »

Exemple de requête

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

curl -L \
  -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