Webhooks

• Scopes & Restrictions
• List hooks
• Get single hook
• Create a hook
• Edit a hook
• Ping a hook
• Delete a hook
• Receiving Webhooks

  application/vnd.github.sersi-preview+json

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"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

[
  {
    "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/:id

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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

The config object can accept the following keys:

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
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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/:id

Parameters

The config object can accept the following keys:

Example

{
  "active": true,
  "events": [
    "pull_request"
  ]
}

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "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/:id/pings

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Delete a hook

DELETE /orgs/:org/hooks/:id

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

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.