Skip to content

Commit f09f9e0

Browse files
author
Hubot
committed
Merge pull request github#657 from github/update-1417636826
2 parents 219d7ba + 7675814 commit f09f9e0

File tree

12 files changed

+578
-85
lines changed

12 files changed

+578
-85
lines changed

‎content/changes/2014-12-03-preview-the-new-organization-webhooks-api.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
kind: change
3+
title: Preview the New Organization Webhooks API
4+
created_at: 2014-12-03
5+
author_name: jdpace
6+
---
7+
8+
Today we're very excited [to announce Organization Webhooks][dotcom-blog-post].
9+
Organization Webhooks allow you to subscribe to events that happen across an
10+
entire organization.
11+
12+
In addition to being able to subscribe to the existing repository oriented
13+
events across an organization, we're also adding some new events which are
14+
exclusive to organization webhooks. The new [`repository`
15+
event][repository-event] allows you to receive webhook payloads when a new
16+
repository is created. By subscribing to the [`membership`
17+
event][membership-event], you'll be notified whenever a user is added or
18+
removed from a team.
19+
20+
We’re making this new API for Organization Webhooks available today [for
21+
developers to preview][docs-preview]. The preview period will allow us to [get
22+
your feedback][contact] before declaring the Organization Webhooks API final.
23+
We expect the preview
24+
period to last for roughly 30-60 days.
25+
26+
As we discover opportunities to improve the API during the preview period, we
27+
may ship changes that break clients using the preview version of the API. We
28+
want to iterate quickly. To do so, we will announce any changes here (on the
29+
developer blog), but we will not provide any advance notice.
30+
31+
At the end of preview period, the Organization Webhooks API will become an
32+
official component of GitHub API v3. At that point, the new Organization
33+
Webhooks API will be stable and suitable for production use.
34+
35+
We hope you’ll take it for a spin and [send us your feedback][contact].
36+
37+
[dotcom-blog-post]: https://github.com/blog/1933-introducing-organization-webhooks
38+
[repository-event]: /v3/activity/events/types/#repositoryevent
39+
[membership-event]: /v3/activity/events/types/#membershipevent
40+
[docs]: /v3/orgs/hooks/
41+
[docs-preview]: /v3/orgs/hooks/#preview-period
42+
[contact]: https://github.com/contact?form[subject]=Organization+Webhooks

‎content/v3/activity/events/types.md‎

Lines changed: 43 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@ title: Event Types & Payloads | GitHub API
55
# Event Types & Payloads
66

77
Each event has a similar JSON schema, but a unique `payload` object that is
8-
determined by its event type.
8+
determined by its event type.
99

1010
Event names are used by [repository webhooks](/v3/repos/hooks/) to specify
1111
which events the webhook should receive. The included payloads below are from webhook deliveries but
1212
match events returned by the [Events API](/v3/activity/events/) (except where noted).
1313

1414

15-
Note that some of these events may not be rendered in timelines.
16-
They're only created for various internal and repository hooks.
15+
**Note:** Some of these events may not be rendered in timelines, they're only
16+
created for various internal and webhook purposes.
1717

1818
* TOC
1919
{:toc}
@@ -279,6 +279,27 @@ Key | Type | Description
279279

280280
<%= webhook_payload "member" %>
281281

282+
## MembershipEvent
283+
284+
Triggered when a user is added or removed from a team.
285+
286+
Events of this type are not visible in timelines, they are only used to trigger organization webhooks.
287+
288+
### Event name
289+
290+
`membership`
291+
292+
### Payload
293+
294+
Key | Type | Description
295+
----|------|-------------
296+
`action` |`string` | The action that was performed. Can be "added" or "removed".
297+
`scope` |`string` | The scope of the membership. Currently, can only be "team".
298+
`member` |`object` | The [user](/v3/users/) that was added or removed.
299+
`team` |`object` | The [team](/v3/orgs/teams/) for the membership.
300+
301+
<%= webhook_payload "membership" %>
302+
282303
## PageBuildEvent
283304

284305
Represents an attempted build of a GitHub Pages site, whether successful or not.
@@ -392,6 +413,25 @@ Key | Type | Description
392413

393414
<%= webhook_payload "release" %>
394415

416+
## RepositoryEvent
417+
418+
Triggered when a repository is created.
419+
420+
Events of this type are not visible in timelines, they are only used to trigger organization webhooks.
421+
422+
### Event name
423+
424+
`repository`
425+
426+
### Payload
427+
428+
Key | Type | Description
429+
----|------|-------------
430+
`action` |`string` | The action that was performed. Currently, can only be "created".
431+
`repository`|`object` | The [repository](/v3/repos/) that was created.
432+
433+
<%= webhook_payload "repository" %>
434+
395435
## StatusEvent
396436

397437
Triggered when the status of a Git commit changes.

‎content/v3/oauth.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,7 @@ Name | Description
183183
`read:repo_hook`| Grants read and ping access to hooks in public or private repositories.
184184
`write:repo_hook`| Grants read, write, and ping access to hooks in public or private repositories.
185185
`admin:repo_hook`| Grants read, write, ping, and delete access to hooks in public or private repositories.
186+
`admin:org_hook`| Grants read, write, ping, and delete access to organization hooks. **Note:** OAuth tokens will only be able to perform these actions on organization hooks which were created by the OAuth application. Personal access tokens will only be able to perform these actions on organization hooks created by a user.
186187
`read:org`| Read-only access to organization, teams, and membership.
187188
`write:org`| Publicize and unpublicize organization membership.
188189
`admin:org`| Fully manage organization, teams, and memberships.

‎content/v3/orgs/hooks.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
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/

‎content/v3/repos/hooks.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Webhooks | GitHub API
2+
title: Repository Webhooks | GitHub API
33
---
44

55
# Webhooks
@@ -11,6 +11,8 @@ The Repository Webhooks API allows repository admins to manage the post-receive
1111
hooks for a repository. Webhooks can be managed using the JSON HTTP API,
1212
or the [PubSubHubbub API](#pubsubhubbub).
1313

14+
If you would like to set up a single webhook to receive events from all of your organization's respositories, check out our [API documentation for Organization Webhooks][org-hooks].
15+
1416
## List hooks
1517

1618
GET /repos/:owner/:repo/hooks
@@ -136,7 +138,7 @@ In order for GitHub to send webhook payloads, your server needs to be accessible
136138

137139
### Webhook Headers
138140

139-
GitHub will send along a few HTTP headers to differentiate between event types and payload identifiers.
141+
GitHub will send along several HTTP headers to differentiate between event types and payload identifiers.
140142

141143
Name | Description
142144
-----|-----------|
@@ -212,3 +214,4 @@ Name | Type | Description
212214
[pshb-secret]: http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html#authednotify
213215
[events-url]: /webhooks/#events
214216
[ping-event-url]: /webhooks/#ping-event
217+
[org-hooks]: /v3/orgs/hooks/

‎content/webhooks/creating/index.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,22 +8,21 @@ layout: webhooks
88
* TOC
99
{:toc}
1010

11-
At their core, webhooks are events generated by GitHub that deliver a payload of
12-
information about activity in a repository. Webhooks can trigger across several
13-
different actions. For example, you can fire a payload of information any time
14-
a commit is made, a repository is forked, or an issue is created.
15-
16-
In this tutorial, our webhook will be responsible for listing out how popular our
17-
repository is, based on the number of Issues it receives per day.
11+
Now that we understand [the basics of webhooks][webhooks-overview], let's go
12+
through the process of building out our own webhook powered integration. In
13+
this tutorial, we'll create a repository webhook that will be responsible for
14+
listing out how popular our repository is, based on the number of Issues it
15+
receives per day.
1816

1917
Creating a webhook is a two-step process. You'll first need to set up how you want
2018
your webhook to behave through GitHub--what events should it listen to. After that,
2119
you'll set up your server to receive and manage the payload.
2220

2321
## Setting up a Webhook
2422

25-
To set up a webhook on GitHub, head over to the **Settings** page of your repository,
26-
and click on **Webhooks & services**. After that, click on **Add webhook**.
23+
To set up a repository webhook on GitHub, head over to the **Settings** page of
24+
your repository, and click on **Webhooks & services**. After that, click on
25+
**Add webhook**.
2726

2827
Alternatively, you can choose to build and manage a webhook [through the Webhooks API][webhook-api].
2928

@@ -62,5 +61,6 @@ When you're finished, click on **Add webhook**. Phew! Now that the webhook is cr
6261
it's time to set up our local server to test the webhook. Head on over to
6362
[Configuring Your Server](/webhooks/configuring/) to learn how to do that.
6463

64+
[webhooks-overview]: /webhooks/
6565
[webhook-api]: /v3/repos/hooks/
6666
[hooks-api]: /webhooks/#events

0 commit comments

Comments
 (0)