This version of GitHub Enterprise was discontinued on 2023-07-06. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

After a site administrator upgrades your Enterprise Server instance to Enterprise Server 3.9 or later, the REST API will be versioned. To learn how to find your instance's version, see "About versions of GitHub Docs". For more information, see "About API versioning."

Organization webhooks

Use the REST API to interact with webhooks in an organization.

About organization webhooks

Organization webhooks allow you to receive HTTP POST payloads whenever certain events happen in an organization. For more information, see "About webhooks."

Scopes and restrictions

All actions against organization webhooks require the authenticated user to be an admin of the organization being managed. Additionally, OAuth tokens require the admin:org_hook scope. For more information, see "Scopes for OAuth apps."

In order to protect sensitive data which may be present in webhook configurations, we also enforce the following access control rules:

OAuth apps cannot list, view, or edit webhooks which they did not create.
Users cannot list, view, or edit webhooks which were created by OAuth apps.

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`org` string Required 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`

HTTP response status codes for "List organization webhooks"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "List organization webhooks"

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

Works with GitHub Apps

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

Parameters for "Create an organization webhook"

Headers

Name, Type, Description

accept string

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

Path parameters

Name, Type, Description

org string Required

The organization name. The name is not case sensitive.

Body parameters

Name, Type, Description

name string Required

Must be passed as "web".

config object Required

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

Properties of config

Name, Type, Description
`url` string Required 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

Organization webhooks

About organization webhooks

Scopes and restrictions

Receiving Webhooks

Webhook headers

List organization webhooks

Parameters for "List organization webhooks"

HTTP response status codes for "List organization webhooks"

Code samples for "List organization webhooks"

Create an organization webhook

Parameters for "Create an organization webhook"