Organization webhooks - GitHub Enterprise Server 3.7 Docs

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

About organization webhooks

Organization webhooks allow your server to receive HTTP POST payloads whenever certain events happen in an organization. For more information, see "Webhooks documentation."

Scopes and restrictions

You must be an organization owner to use these endpoints. OAuth tokens require the admin:org_hook scope to use these endpoints.

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.

List organization webhooks

Works with GitHub Apps

Parameters for "List organization webhooks"

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.

Name, Type, Description

name string Required

Must be passed as "web".

config object Required

Key/value pairs to provide settings for this webhook.

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

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

HTTP response status codes for "Create an organization webhook"

Status code	Description
`201`	Created
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples for "Create an organization webhook"

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

Works with GitHub Apps

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

Parameters for "Get 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.
`hook_id` integer Required The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

HTTP response status codes for "Get an organization webhook"

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

Code samples for "Get an organization webhook"

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

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

Parameters for "Update 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.
`hook_id` integer Required The unique identifier of the hook. You can find this value in the `X-GitHub-Hook-ID` header of a webhook delivery.

Body parameters
Name, Type, Description
`config` object Key/value pairs to provide settings for this webhook.
Properties of