Webhooks
- Scopes & Restrictions
- List hooks
- Get single hook
- Create a hook
- Edit a hook
- Ping a hook
- Delete a hook
- Receiving Webhooks
Organization webhooks allow you to receive HTTP POST
payloads whenever certain events happen within the organization. Subscribing to these events makes it possible to build integrations that react to actions on GitHub.com. For more information on actions you can subscribe to, check out our Events documentation.
Scopes & 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.
In order to protect sensitive data which may be present in webhook configurations, we also enforce the following access control rules:
- OAuth applications cannot list, view, or edit webhooks which they did not create.
- Users cannot list, view, or edit webhooks which were created by OAuth applications.
List hooks
GET /orgs/:org/hooks
Response
Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
<https://api.github.com/resource?page=5>; rel="last"
[
{
"id": 1,
"url": "https://api.github.com/orgs/octocat/hooks/1",
"ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
"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"
}
]
Get single hook
GET /orgs/:org/hooks/:hook_id
Response
Status: 200 OK
{
"id": 1,
"url": "https://api.github.com/orgs/octocat/hooks/1",
"ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
"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"
}
Create a hook
POST /orgs/:org/hooks
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. |
events |
array |
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 . |
The config
object can accept the following keys:
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 in the X-Hub-Signature header. |
insecure_ssl |
string |
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.
|
Example
Here's how you can create a hook that posts payloads in JSON format:
{
"name": "web",
"active": true,
"events": [
"push",
"pull_request"
],
"config": {
"url": "http://example.com/webhook",
"content_type": "json"
}
}
Response
Status: 201 Created
Location: https://api.github.com/orgs/octocat/hooks/1
{
"id": 1,
"url": "https://api.github.com/orgs/octocat/hooks/1",
"ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
"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"
}
Edit a hook
PATCH /orgs/:org/hooks/:hook_id
Parameters
Name | Type | Description |
---|---|---|
config |
object |
Key/value pairs to provide settings for this webhook. These are defined below. |
events |
array |
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 . |
The config
object can accept the following keys:
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 in the X-Hub-Signature header. |
insecure_ssl |
string |
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.
|
Example
{
"active": true,
"events": [
"pull_request"
]
}
Response
Status: 200 OK
{
"id": 1,
"url": "https://api.github.com/orgs/octocat/hooks/1",
"ping_url": "https://api.github.com/orgs/octocat/hooks/1/pings",
"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"
}
Ping a hook
This will trigger a ping event to be sent to the hook.
POST /orgs/:org/hooks/:hook_id/pings
Response
Status: 204 No Content
Delete a hook
DELETE /orgs/:org/hooks/:hook_id
Response
Status: 204 No Content
Receiving Webhooks
In order for GitHub to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.
For more best practices, see our guide.
Webhook headers
GitHub will send along several HTTP headers to differentiate between event types and payload identifiers. See webhook headers for details.