|
| 1 | +--- |
| 2 | +title: Organization Webhooks | GitHub API |
| 3 | +--- |
| 4 | + |
| 5 | +# Webhooks |
| 6 | + |
| 7 | +* TOC |
| 8 | +{:toc} |
| 9 | + |
| 10 | +{{#tip}} |
| 11 | + |
| 12 | + <a name="preview-period"></a> |
| 13 | + |
| 14 | + The Organization Webhooks API is currently available for developers to preview. |
| 15 | + During the preview period, the API may change without advance notice. |
| 16 | + Please see the [blog post][developer-blog-post] for full details. |
| 17 | + |
| 18 | + To access the API during the preview period, you must provide a custom [media type][media-type] in the `Accept` header: |
| 19 | + |
| 20 | + application/vnd.github.sersi-preview+json |
| 21 | + |
| 22 | +{{/tip}} |
| 23 | + |
| 24 | + |
| 25 | +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][webhook-events]. |
| 26 | + |
| 27 | +## Scopes & Restrictions |
| 28 | + |
| 29 | +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](/v3/oauth/#scopes). |
| 30 | + |
| 31 | +In order to protect sensitive data which may be present in webhook configurations, we also enforce the following access control rules: |
| 32 | + |
| 33 | +- OAuth applications cannot list, view, or edit webhooks which they did not create. |
| 34 | +- Users cannot list, view, or edit webhooks which were created by OAuth applications. |
| 35 | + |
| 36 | +## List hooks |
| 37 | + |
| 38 | + GET /orgs/:org/hooks |
| 39 | + |
| 40 | +### Response |
| 41 | + |
| 42 | +<%= headers 200, :pagination => default_pagination_rels %> |
| 43 | +<%= json(:org_hook) { |h| [h] } %> |
| 44 | + |
| 45 | + |
| 46 | +## Get single hook |
| 47 | + |
| 48 | + GET /orgs/:org/hooks/:id |
| 49 | + |
| 50 | +### Response |
| 51 | + |
| 52 | +<%= headers 200 %> |
| 53 | +<%= json :org_hook %> |
| 54 | + |
| 55 | + |
| 56 | +## Create a hook |
| 57 | + |
| 58 | + POST /orgs/:org/hooks |
| 59 | + |
| 60 | +### Parameters |
| 61 | + |
| 62 | +Name | Type | Description |
| 63 | +-----|------|-------------- |
| 64 | +`name`|`string` | **Required**. Must be passed as "web". |
| 65 | +`config`|`hash` | **Required**. Key/value pairs to provide settings for this webhook. [These are defined below](#create-hook-config-params). |
| 66 | +`events`|`array` | Determines what [events][event-types] the hook is triggered for. Default: `["push"]`. |
| 67 | +`active`|`boolean` | Determines whether the hook is actually triggered on pushes. |
| 68 | + |
| 69 | +<a name="create-hook-config-params"></a> |
| 70 | +The `config` hash can accept the following keys: |
| 71 | + |
| 72 | +<%= fetch_content(:org_hook_config_hash) %> |
| 73 | + |
| 74 | +#### Example |
| 75 | + |
| 76 | +Here's how you can create a hook that posts payloads in JSON format: |
| 77 | + |
| 78 | +<%= json \ |
| 79 | + :name => "web", |
| 80 | + :active => true, |
| 81 | + :events => ['push', 'pull_request'], |
| 82 | + :config => { |
| 83 | + :url => 'http://example.com/webhook', |
| 84 | + :content_type => 'json'} |
| 85 | +%> |
| 86 | + |
| 87 | +### Response |
| 88 | + |
| 89 | +<%= headers 201, |
| 90 | + :Location => 'https://api.github.com/orgs/octocat/hooks/1' %> |
| 91 | +<%= json :org_hook %> |
| 92 | + |
| 93 | + |
| 94 | +## Edit a hook |
| 95 | + |
| 96 | + PATCH /orgs/:org/hooks/:id |
| 97 | + |
| 98 | +### Parameters |
| 99 | + |
| 100 | +Name | Type | Description |
| 101 | +-----|------|-------------- |
| 102 | +`config`|`hash` | **Required**. Key/value pairs to provide settings for this webhook. [These are defined below](#update-hook-config-params). |
| 103 | +`events`|`array` | Determines what [events][event-types] the hook is triggered for. Default: `["push"]`. |
| 104 | +`active`|`boolean` | Determines whether the hook is actually triggered on pushes. |
| 105 | + |
| 106 | +<a name="update-hook-config-params"></a> |
| 107 | +The `config` hash can accept the following keys: |
| 108 | + |
| 109 | +<%= fetch_content(:org_hook_config_hash) %> |
| 110 | + |
| 111 | + |
| 112 | +#### Example |
| 113 | + |
| 114 | +<%= json \ |
| 115 | + :active => true, |
| 116 | + :events => ['pull_request'] |
| 117 | +%> |
| 118 | + |
| 119 | +### Response |
| 120 | + |
| 121 | +<%= headers 200 %> |
| 122 | +<%= json(:org_hook) { |h| h.merge "events" => %w(pull_request) } %> |
| 123 | + |
| 124 | + |
| 125 | +## Ping a hook |
| 126 | + |
| 127 | +This will trigger a [ping event][ping-event-url] to be sent to the hook. |
| 128 | + |
| 129 | + POST /orgs/:org/hooks/:id/pings |
| 130 | + |
| 131 | +### Response |
| 132 | + |
| 133 | +<%= headers 204 %> |
| 134 | + |
| 135 | + |
| 136 | +## Delete a hook |
| 137 | + |
| 138 | + DELETE /orgs/:org/hooks/:id |
| 139 | + |
| 140 | +### Response |
| 141 | + |
| 142 | +<%= headers 204 %> |
| 143 | + |
| 144 | + |
| 145 | +## Receiving Webhooks |
| 146 | + |
| 147 | +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. |
| 148 | + |
| 149 | +For more best practices, [see our guide][best-integration-practices]. |
| 150 | + |
| 151 | +### Webhook Headers |
| 152 | + |
| 153 | +GitHub will send along several HTTP headers to differentiate between event types and payload identifiers. |
| 154 | + |
| 155 | +Name | Description |
| 156 | +-----|-----------| |
| 157 | +`X-GitHub-Event` | The [event type](/v3/activity/events/types/) that was triggered. |
| 158 | +`X-GitHub-Delivery` | A [guid][guid] to identify the payload and event being sent. |
| 159 | +`X-Hub-Signature` | The value of this header is computed as the HMAC hex digest of the body, using the `secret` config option as the key. |
| 160 | + |
| 161 | + |
| 162 | +[guid]: http://en.wikipedia.org/wiki/Globally_unique_identifier |
| 163 | +[hub-signature]: https://github.com/github/github-services/blob/f3bb3dd780feb6318c42b2db064ed6d481b70a1f/lib/service/http_helper.rb#L77 |
| 164 | +[ping-event-url]: /webhooks/#ping-event |
| 165 | +[webhook-events]: /webhooks/#events |
| 166 | +[event-types]: /v3/activity/events/types/ |
| 167 | +[media-type]: /v3/media |
| 168 | +[best-integration-practices]: /guides/best-practices-for-integrators/ |
| 169 | +[developer-blog-post]: /changes/2014-12-03-preview-the-new-organization-webhooks-api/ |
0 commit comments