The REST API is now versioned. For more information, see "About API versioning."

Webhooks d’organisation

À propos de l’API Webhooks d’organisation

Les webhooks d’organisation vous permettent de recevoir des charges utiles HTTP POST chaque fois que certains événements se produisent dans une organisation. Vous pouvez utiliser l’API REST pour gérer les webhooks de dépôt, d’organisation et d’application. Vous pouvez lister les livraisons d’un webhook, ou obtenir et refaire une livraison individuelle d’un webhook, qui peut être intégré dans une application ou un service externe. Vous pouvez également utiliser l’API REST pour changer la configuration du webhook. Par exemple, vous pouvez modifier l’URL de charge utile, le type de contenu, la vérification SSL et le secret. Pour plus d'informations, consultez les pages suivantes :

Pour plus d’informations sur les actions auxquelles vous pouvez vous abonner, consultez « GitHub types d’événements ».

Étendues et restrictions

Toutes les actions contre les webhooks d’organisation nécessitent que l’utilisateur authentifié soit administrateur de l’organisation en cours de gestion. En outre, les jetons OAuth requièrent l’étendue admin:org_hook. Pour plus d’informations, consultez « Étendues pour les applications OAuth ».

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 :

Les applications OAuth ne peuvent pas répertorier, afficher ou modifier des webhooks qu’elles n’ont pas créés.
Les utilisateurs ne peuvent pas répertorier, afficher ou modifier des webhooks créés par des applications OAuth.

Réception de webhooks

Pour que GitHub envoie des charges utiles de webhook, votre serveur doit être accessible à partir d’Internet. Nous vous suggérons également vivement d’utiliser SSL afin que nous puissions envoyer des charges utiles chiffrées via HTTPS.

Pour d’autres meilleures pratiques, consultez notre guide.

En-têtes de webhook

GitHub envoie plusieurs en-têtes HTTP pour différencier les types d’événements et les identificateurs de charge utile. Consultez En-têtes de webhook pour plus de détails.

List organization webhooks

Fonctionne avec GitHub Apps

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). Default: `30`
`page`integer Page number of the results to fetch. Default: `1`

Codes de statut de réponse HTTP

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

Exemples de code

get/orgs/{org}/hooks

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

Fonctionne avec GitHub Apps

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

Paramètres

Headers

Name, Type, Description

acceptstring

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

Path parameters

Name, Type, Description

orgstringRequired

The organization name. The name is not case sensitive.

Body parameters

Name, Type, Description

namestringRequired

Must be passed as "web".

configobjectRequired

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

Properties of config

Name, Type, Description
`url`stringRequired 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.

Default: ["push"]

activeboolean

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

Default: true

Codes de statut de réponse HTTP

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

Exemples de code

post/orgs/{org}/hooks

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

Fonctionne avec GitHub Apps

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

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

Codes de statut de réponse HTTP

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

Exemples de code

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

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

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

Paramètres

Headers

Name, Type, Description

acceptstring

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

Path parameters

Name, Type, Description

orgstringRequired

The organization name. The name is not case sensitive.

hook_idintegerRequired

The unique identifier of the hook.

Body parameters

Name, Type, Description

configobject

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

Properties of config

Name, Type, Description
`url`stringRequired 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.

Default: ["push"]

activeboolean

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

Default: true

namestring

Codes de statut de réponse HTTP

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

Exemples de code

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

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

Fonctionne avec GitHub Apps

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

Codes de statut de réponse HTTP

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

Exemples de code

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

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

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

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

Codes de statut de réponse HTTP

Code d’état	Description
`200`	OK

Exemples de code

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

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

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

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
Body parameters
Name, 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 de statut de réponse HTTP

Code d’état	Description
`200`	OK

Exemples de code

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

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

Fonctionne avec GitHub Apps

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

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). 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 de statut de réponse HTTP

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

Exemples de code

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

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

Fonctionne avec GitHub Apps

Returns a delivery for a webhook configured in an organization.

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
`delivery_id`integerRequired

Codes de statut de réponse HTTP

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

Exemples de code

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

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

Fonctionne avec GitHub Apps

Redeliver a delivery for a webhook configured in an organization.

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.
`delivery_id`integerRequired

Codes de statut de réponse HTTP

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

Exemples de code

post/orgs/{org}/hooks/{hook_id}/deliveries/{delivery_id}/attempts

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

Fonctionne avec GitHub Apps

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

Paramètres

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org`stringRequired The organization name. The name is not case sensitive.
`hook_id`integerRequired The unique identifier of the hook.

Codes de statut de réponse HTTP

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

Exemples de code

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

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