Skip to main content
L’API REST est maintenant versionnée. Pour plus d’informations, consultez « À propos des versions de l’API ».

Webhooks d’organisation

Utilisez l’API REST pour interagir avec les webhooks d’une organisation.

À propos des 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. Pour plus d’informations, consultez « À propos des webhooks ».

É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 des 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 :

  • OAuth apps ne peuvent pas lister, visualiser ou modifier les webhooks qu’ils n’ont pas créés.
  • Les utilisateurs ne peuvent pas lister, voir ou modifier les webhooks qui ont été créés par OAuth apps.

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

Compatible avec GitHub 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).

Default: 30

page integer

Page number of the results to fetch.

Default: 1

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

Code d’étatDescription
200

OK

404

Resource not found

Exemples de code pour « List organization webhooks »

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

Compatible avec GitHub Apps

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

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.

Paramètres du corps
Nom, Type, Description
name string Obligatoire

Must be passed as "web".

config object Obligatoire

Key/value pairs to provide settings for this webhook.

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’étatDescription
201

Created

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

Exemples de code pour « Create an organization webhook »

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

Compatible 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 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’étatDescription
200

OK

404

Resource not found

Exemples de code pour « Get an organization webhook »

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

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

Paramètres du corps
Nom, Type, Description
config object

Key/value pairs to provide settings for this webhook.

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’étatDescription
200

OK

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

Exemples de code pour « Update an organization webhook »

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

Compatible avec GitHub 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’étatDescription
204

No Content

404

Resource not found

Exemples de code pour « Delete an organization webhook »

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

Compatible 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 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’étatDescription
200

OK

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

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

Compatible 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 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’étatDescription
200

OK

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

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

Compatible avec GitHub Apps

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

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

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’étatDescription
200

OK

400

Bad Request

422

Validation failed, or the endpoint has been spammed.

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

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

Compatible avec GitHub Apps

Returns a delivery for a webhook configured in an organization.

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’étatDescription
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 »

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

Compatible avec GitHub Apps

Redeliver a delivery for a webhook configured in an organization.

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’étatDescription
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 »

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

Compatible avec GitHub Apps

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

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’étatDescription
204

No Content

404

Resource not found

Exemples de code pour « Ping an organization webhook »

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