Skip to content

Commit 9c65d8d

Browse files
gjtorikiangjtorikian
committed
Merge pull request github#429 from github/add-hooks-part-ii
Add hooks part ii
2 parents 3131e79 + 24df454 commit 9c65d8d

File tree

15 files changed

+237
-195
lines changed

15 files changed

+237
-195
lines changed

‎changes/index.html‎

Lines changed: 51 additions & 52 deletions
Large diffs are not rendered by default.

‎content/changes/2014-02-10-repo-hook-scopes.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@ in your repositories. Today, we've introduced three new [scopes][] that provide
1010
more granular access to your repository hooks without allowing access to your
1111
repository contents:
1212

13-
* `read:repo_hook` grants read access to hooks in public or private repositories.
14-
* `write:repo_hook` grants read and write access to hooks in public or private repositories.
15-
* `admin:repo_hook` grants read, write, and delete access to hooks in public or private repositories.
13+
* `read:repo_hook` grants read and ping access to hooks in public or private repositories.
14+
* `write:repo_hook` grants read, write, and ping access to hooks in public or private repositories.
15+
* `admin:repo_hook` grants read, write, ping, and delete access to hooks in public or private repositories.
1616

1717
As always, if you have any questions or feedback, [get in touch][contact].
1818

‎content/changes/2014-2-10-ping-event-for-webhooks.html‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
kind: change
3+
title: Ping Event for Webhooks
4+
created_at: 2014-2-10
5+
author_name: kdaigle
6+
---
7+
8+
With the release of our [new webhook UI](#), we included a new
9+
[ping event](/v3/repos/hooks/#ping-event) that webhooks will receive. When you
10+
create a new webhook, we will send this event as an initial test of the webhook.
11+
12+
The ping is only informational, doesn't need to be responded to in a specific way,
13+
and nothing bad will happen if you respond with an error. It's just a quick
14+
"hello world" to let you know you set everything up correctly.
15+
16+
We also added a [ping endpoint](/v3/repos/hooks/#ping-a-hook) to the hooks API.
17+
By using ping instead of [test](/v3/repos/hooks/#test-a-push-hook), you can ensure
18+
you won't be limited by the `push` event requirement that the test endpoint has.

‎content/v3/oauth.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -171,9 +171,9 @@ Name | Description
171171
`delete_repo`| Grants access to delete adminable repositories.
172172
`notifications`| Grants read access to a user's notifications. `repo` also provides this access.
173173
`gist`| Grants write access to gists.
174-
`read:repo_hook`| Grants read access to hooks in public or private repositories.
175-
`write:repo_hook`| Grants read and write access to hooks in public or private repositories.
176-
`admin:repo_hook`| Grants read, write, and delete access to hooks in public or private repositories.
174+
`read:repo_hook`| Grants read and ping access to hooks in public or private repositories.
175+
`write:repo_hook`| Grants read, write, and ping access to hooks in public or private repositories.
176+
`admin:repo_hook`| Grants read, write, ping, and delete access to hooks in public or private repositories.
177177

178178
NOTE: Your application can request the scopes in the initial redirection. You
179179
can specify multiple scopes by separating them with a comma:

‎content/v3/repos/hooks.md‎

Lines changed: 30 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -8,110 +8,32 @@ title: Webhooks | GitHub API
88
{:toc}
99

1010
The Repository Webhooks API allows repository admins to manage the post-receive
11-
hooks for a repository. Webhooks can be managed using the [JSON HTTP API](#json-http)
12-
and the [PubSubHubbub API](#pubsubhubbub).
11+
hooks for a repository. Webhooks can be managed using the JSON HTTP API,
12+
or the [PubSubHubbub API](#pubsubhubbub).
1313

14-
Each hook can be configured for a specific [service](#services) and one or
15-
more [events](#events), regardless of the API used to do so.
16-
17-
## Services
18-
19-
A service is basically the name used to refer to a hook that has configuration
20-
settings, a list of available events, and default events.
21-
22-
> For instance, the
23-
[email](https://github.com/github/github-services/blob/master/lib/services/email.rb)
24-
service is a built-in GitHub service that will send event [payloads](#payloads)
25-
to, at most, two email addresses. It will trigger for the `push`
26-
event by default and supports the `public` event type as well.
27-
28-
A number of services have been integrated through the open source
29-
[github-services](https://github.com/github/github-services) project. When
30-
creating a [hook](#create-a-hook), the `:name` parameter must refer to one of
31-
these services. A generic
32-
[Web](https://github.com/github/github-services/blob/master/lib/services/web.rb)
33-
service is available that can configured to trigger for any of the available
34-
[events](#events).
35-
36-
Documentation for all available service hooks can be found in the
37-
[docs directory](https://github.com/github/github-services/tree/master/docs)
38-
of the github-services repository. A JSON representation of their names,
39-
default events, supported events, and configuration options can be seen
40-
at [api.github.com/hooks](https://api.github.com/hooks).
41-
42-
43-
## Events
44-
45-
Active hooks can be configured to trigger for one or more service supported
46-
events. In other words, the service must support listening for the event you
47-
want to trigger.
48-
49-
For example, the
50-
[Web](https://github.com/github/github-services/blob/master/lib/services/web.rb)
51-
service listens for all events, while the
52-
[IRC](https://github.com/github/github-services/blob/master/lib/services/irc.rb)
53-
service can only listen for `push`, `issues`, and `pull_request` events.
54-
55-
The available events are:
56-
57-
Name | Description
58-
-----|-----------|
59-
`push` | Any git push to a Repository. **This is the default event.**
60-
`issues` | Any time an Issue is opened or closed.
61-
`issue_comment` | Any time an Issue is commented on.
62-
`commit_comment` | Any time a Commit is commented on.
63-
`create` | Any time a Repository, Branch, or Tag is created.
64-
`delete` | Any time a Branch or Tag is deleted.
65-
`pull_request` | Any time a Pull Request is opened, closed, or synchronized (updated due to a new push in the branch that the pull request is tracking).
66-
`pull_request_review_comment` | Any time a Commit is commented on while inside a Pull Request review (the Files Changed tab).
67-
`gollum` | Any time a Wiki page is updated.
68-
`watch` | Any time a User watches the Repository.
69-
`release` | Any time a Release is published in the Repository.
70-
`fork` | Any time a Repository is forked.
71-
`member` | Any time a User is added as a collaborator to a non-Organization Repository.
72-
`public` | Any time a Repository changes from private to public.
73-
`team_add` | Any time a team is added or modified on a Repository.
74-
`status` | Any time a Repository has a status update from the API
75-
`deployment` | Any time a Repository has a new deployment created from the API.
76-
`deployment_status` | Any time a deployment for the Repository has a status update from the API.
77-
78-
79-
### Payloads
80-
81-
The payloads for all hooks mirror [the payloads for the Event
82-
types](/v3/activity/events/types/), with the exception of [the original `push`
83-
event](http://help.github.com/post-receive-hooks/),
84-
which has a more detailed payload.
85-
86-
87-
## JSON HTTP
88-
89-
The JSON HTTP API follows the same conventions as the rest of the
90-
[GitHub API](http://developer.github.com/v3/).
91-
92-
### List
14+
## List hooks
9315

9416
GET /repos/:owner/:repo/hooks
9517

96-
#### Response
18+
### Response
9719

9820
<%= headers 200, :pagination => default_pagination_rels %>
9921
<%= json(:hook) { |h| [h] } %>
10022

101-
### Get single hook
23+
## Get single hook
10224

10325
GET /repos/:owner/:repo/hooks/:id
10426

105-
#### Response
27+
### Response
10628

10729
<%= headers 200 %>
10830
<%= json :hook %>
10931

110-
### Create a hook
32+
## Create a hook
11133

11234
POST /repos/:owner/:repo/hooks
11335

114-
#### Parameter
36+
### Parameter
11537

11638
Name | Type | Description
11739
-----|------|--------------
@@ -120,7 +42,7 @@ Name | Type | Description
12042
`events`|`array` | Determines what events the hook is triggered for. Default: `["push"]`
12143
`active`|`boolean` | Determines whether the hook is actually triggered on pushes.
12244

123-
##### Example
45+
#### Example
12446

12547
The ["web" service hook](https://github.com/github/github-services/blob/master/lib/services/web.rb#L4-11)
12648
takes these fields in the `config`:
@@ -143,17 +65,17 @@ Here's how you can setup a hook that posts payloads in JSON format:
14365
:content_type => 'json'}
14466
%>
14567

146-
#### Response
68+
### Response
14769

14870
<%= headers 201,
14971
:Location => 'https://api.github.com/repos/user/repo/hooks/1' %>
15072
<%= json :hook %>
15173

152-
### Edit a hook
74+
## Edit a hook
15375

15476
PATCH /repos/:owner/:repo/hooks/:id
15577

156-
#### Parameter
78+
### Parameter
15779

15880
Name | Type | Description
15981
-----|------|--------------
@@ -164,19 +86,19 @@ Name | Type | Description
16486
`active`|`boolean` | Determines whether the hook is actually triggered on pushes.
16587

16688

167-
##### Example
89+
#### Example
16890

16991
<%= json \
17092
:active => true,
17193
:add_events => ['pull_request']
17294
%>
17395

174-
#### Response
96+
### Response
17597

17698
<%= headers 200 %>
17799
<%= json :hook %>
178100

179-
### Test a `push` hook
101+
## Test a `push` hook
180102

181103
This will trigger the hook with the latest push to the current
182104
repository if the hook is subscribed to `push` events. If the
@@ -187,15 +109,25 @@ with 204 but no test POST will be generated.
187109

188110
**Note**: Previously `/repos/:owner/:repo/hooks/:id/test`
189111

190-
#### Response
112+
### Response
113+
114+
<%= headers 204 %>
115+
116+
## Ping a hook
117+
118+
This will trigger a [ping event][ping-event-url] to be sent to the hook.
119+
120+
POST /repos/:owner/:repo/hooks/:id/pings
121+
122+
### Response
191123

192124
<%= headers 204 %>
193125

194126
## Delete a hook
195127

196128
DELETE /repos/:owner/:repo/hooks/:id
197129

198-
#### Response
130+
### Response
199131

200132
<%= headers 204 %>
201133

@@ -209,7 +141,7 @@ Topic URLs for a GitHub repository's pushes are in this format:
209141

210142
https://github.com/:owner/:repo/events/:event
211143

212-
The event can be any [event](#events) string that is listed at the top of this
144+
The event can be any [event][events-url] string that is listed at the top of this
213145
document.
214146

215147
### Response format
@@ -264,3 +196,5 @@ Name | Type | Description
264196
[ruby-secret]: https://github.com/github/github-services/blob/14f4da01ce29bc6a02427a9fbf37b08b141e81d9/lib/services/web.rb#L47-L50
265197
[hub-signature]: https://github.com/github/github-services/blob/f3bb3dd780feb6318c42b2db064ed6d481b70a1f/lib/service/http_helper.rb#L77
266198
[pshb-secret]: http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html#authednotify
199+
[events-url]: /webhooks/#events
200+
[ping-event-url]: /webhooks/#ping-event

‎content/webhooks/index.md‎

Lines changed: 89 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,97 @@ title: Webhooks | GitHub API
33
layout: webhooks
44
---
55

6+
* TOC
7+
{:toc}
8+
69
Every GitHub repository has the option to communicate with a web server whenever
710
the repository is pushed to. These "webhooks" can be used to update an external
811
issue tracker, trigger CI builds, update a backup mirror, or even deploy to your
912
production server.
1013

11-
This section of the GitHub Developer Guide will instruct you on how to develop, configure,
12-
and test your first webhook.
14+
Each hook can be configured for a specific [service](#services) and one or
15+
more [events](#events), regardless of the API used to do so. Repository admins
16+
can configure hooks programmatically [via the API](/v3/repos/hooks/).
17+
18+
## Services
19+
20+
A service is basically the name used to refer to a hook that has configuration
21+
settings, a list of available events, and default events.
22+
23+
> For instance, the
24+
[email](https://github.com/github/github-services/blob/master/lib/services/email.rb)
25+
service is a built-in GitHub service that will send event [payloads](#payloads)
26+
to, at most, two email addresses. It will trigger for the `push`
27+
event by default and supports the `public` event type as well.
28+
29+
A number of services have been integrated through the open source
30+
[github-services](https://github.com/github/github-services) project. When
31+
creating a [hook](#create-a-hook), the `:name` parameter must refer to one of
32+
these services. A generic
33+
[Web](https://github.com/github/github-services/blob/master/lib/services/web.rb)
34+
service is available that can configured to trigger for any of the available
35+
[events](#events).
36+
37+
Documentation for all available service hooks can be found in the
38+
[docs directory](https://github.com/github/github-services/tree/master/docs)
39+
of the github-services repository. A JSON representation of their names,
40+
default events, supported events, and configuration options can be seen
41+
at [api.github.com/hooks](https://api.github.com/hooks).
42+
43+
44+
## Events
45+
46+
Active hooks can be configured to trigger for one or more service supported
47+
events. In other words, the service must support listening for the event you
48+
want to trigger.
49+
50+
For example, the
51+
[Web](https://github.com/github/github-services/blob/master/lib/services/web.rb)
52+
service listens for all events, while the
53+
[IRC](https://github.com/github/github-services/blob/master/lib/services/irc.rb)
54+
service can only listen for `push`, `issues`, and `pull_request` events.
55+
56+
The available events are:
57+
58+
Name | Description
59+
-----|-----------|
60+
`push` | Any git push to a Repository. **This is the default event.**
61+
`issues` | Any time an Issue is opened or closed.
62+
`issue_comment` | Any time an Issue is commented on.
63+
`commit_comment` | Any time a Commit is commented on.
64+
`create` | Any time a Repository, Branch, or Tag is created.
65+
`delete` | Any time a Branch or Tag is deleted.
66+
`pull_request` | Any time a Pull Request is opened, closed, or synchronized (updated due to a new push in the branch that the pull request is tracking).
67+
`pull_request_review_comment` | Any time a Commit is commented on while inside a Pull Request review (the Files Changed tab).
68+
`gollum` | Any time a Wiki page is updated.
69+
`watch` | Any time a User watches the Repository.
70+
`release` | Any time a Release is published in the Repository.
71+
`fork` | Any time a Repository is forked.
72+
`member` | Any time a User is added as a collaborator to a non-Organization Repository.
73+
`public` | Any time a Repository changes from private to public.
74+
`team_add` | Any time a team is added or modified on a Repository.
75+
`status` | Any time a Repository has a status update from the API
76+
`deployment` | Any time a Repository has a new deployment created from the API.
77+
`deployment_status` | Any time a deployment for the Repository has a status update from the API.
78+
79+
80+
### Payloads
81+
82+
The payloads for all hooks mirror [the payloads for the Event
83+
types](/v3/activity/events/types/), with the exception of [the original `push`
84+
event](http://help.github.com/post-receive-hooks/),
85+
which has a more detailed payload.
86+
87+
## Ping Event
88+
89+
When you create a new webhook, we'll send you a simple `ping` event to let you
90+
know you've set up the webhook correctly. This event isn't stored so it isn't
91+
retrievable via the [Events API](/v3/activity/events/). You can trigger a `ping`
92+
again by calling the [ping endpoint](#).
93+
94+
### Ping Event Payload
95+
96+
Key | Value |
97+
----| ----- |
98+
zen | Random string of GitHub zen |
99+
hook_id | The ID of the webhook that triggered the ping |

0 commit comments

Comments
 (0)