8000 update hook docs to talk about Hook#events · meeech/developer.github.com@63502d1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 63502d1

Browse files
technoweenietechnoweenie
committed
update hook docs to talk about Hook#events
1 parent c3fb85a commit 63502d1

File tree

2 files changed

+55
-13
lines changed

2 files changed

+55
-13
lines changed

‎content/v3/repos/hooks.md‎

Lines changed: 52 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,30 @@ The Repository Hooks API manages the post-receive web and service hooks
88
for a repository. There are two main APIs to manage these hooks: a JSON
99
HTTP API, and [PubSubHubbub](#pubsubhubbub).
1010

11+
Active hooks can be configured to trigger for one or more events.
12+
The default event is `push`. The available events are:
13+
14+
* `push` - Any git push to a Repository.
15+
* `issues` - Any time an Issue is opened or closed.
16+
* `issue_comment` - Any time an Issue is commented on.
17+
* `commit_comment` - Any time a Commit is commented on.
18+
* `pull_request` - Any time a Pull Request is opend, closed, or
19+
synchronized (updated due to a new push in the branch that the pull
20+
request is tracking).
21+
* `gollum` - Any time a Wiki page is updated.
22+
* `watch` - Any time a User watches the Repository.
23+
* `download` - Any time a Download is added to the Repository.
24+
* `fork` - Any time a Repository is forked.
25+
* `fork_apply` - Any time a patch is applied to the Repository from the
26+
Fork Queue.
27+
* `member` - Any time a User is added as a collaborator to a
28+
non-Organization Repository.
29+
* `public` - Any time a Repository changes from private to public.
30+
31+
For a Hook to go through, the Hook needs to be configured to trigger for
32+
an event, and the Service has to listen to it. The Services are all
33+
part of the open source [github-services](https://github.com/github/github-services) project.Most of the Services only listen for `push` events. However, the generic [Web Service](https://github.com/github/github-services/blob/master/services/web.rb) listens for all events. Other services like the [IRC Service](https://github.com/github/github-services/blob/master/services/irc.rb) may only listen for `push`, `issues`, and `pull_request` events.
34+
1135
## List
1236

1337
GET /repos/:user/:repo/hooks
@@ -24,7 +48,7 @@ HTTP API, and [PubSubHubbub](#pubsubhubbub).
2448
### Response
2549

2650
<%= headers 200 %>
27-
<%= json :full_hook %>
51+
<%= json :hook %>
2852

2953
## Create a hook
3054

@@ -42,24 +66,26 @@ settings for this hook. These settings vary between the services and
4266
are defined in the
4367
[github-services](https://github.com/github/github-services) repo.
4468

69+
events
70+
: _Optional_ **array** - Determines what events the hook is triggered
71+
for. Default: `["push"]`.
72+
4573
active
4674
: _Optional_ **boolean** - Determines whether the hook is actually
4775
triggered on pushes.
4876

4977
<%= json \
50-
:name => "campfire",
78+
:name => "web",
5179
:active => true,
5280
:config => {
53-
:subdomain => 'github',
54-
:room => 'Commits',
55-
:token => 'abc123'}
81+
:url => 'http://something.com/webhook'}
5682
%>
5783

5884
### Response
5985

6086
<%= headers 201,
6187
:Location => 'https://api.github.com/repos/user/repo/hooks/1' %>
62-
<%= json :full_hook %>
88+
<%= json :hook %>
6389

6490
### Edit a hook
6591

@@ -73,10 +99,23 @@ See [/hooks](https://api.github.com/hooks) for the possible names.
7399

74100
config
75101
: _Required_ **hash** - A Hash containing key/value pairs to provide
76-
settings for this hook. These settings vary between the services and
102+
settings for this hook. Modifying this will replace the entire config
103+
object. These settings vary between the services and
77104
are defined in the
78105
[github-services](https://github.com/github/github-services) repo.
79106

107+
events
108+
: _Optional_ **array** - Determines what events the hook is triggered
109+
for. This replaces the entire array of events. Default: `["push"]`.
110+
111+
add_events
112+
: _Optional_ **array** - Determines a list of events to be added to the
113+
list of events that the Hook triggers for.
114+
115+
remove_events
116+
: _Optional_ **array** - Determines a list of events to be removed from the
117+
list of events that the Hook triggers for.
118+
80119
active
81120
: _Optional_ **boolean** - Determines whether the hook is actually
82121
triggered on pushes.
@@ -93,7 +132,7 @@ triggered on pushes.
93132
### Response
94133

95134
<%= headers 200 %>
96-
<%= json :full_hook %>
135+
<%= json :hook %>
97136

98137
## Test a hook
99138

@@ -118,7 +157,10 @@ repository.
118157

119158
GitHub can also serve as a [PubSubHubbub][pubsub] hub for all repositories. PSHB is a simple publish/subscribe protocol that lets servers register to receive updates when a topic is updated. The updates are sent with an HTTP POST request to a callback URL. Topic URLs for a GitHub repository's pushes are in this format:
120159

121-
https://github.com/:user/:repo/events/push
160+
https://github.com/:user/:repo/events/:event
161+
162+
The event can be any Event string that is listed at the top of this
163+
document.
122164

123165
The default format is what [existing post-receive hooks should
124166
expect][post-receive]: A JSON body sent as the `payload` parameter in a
@@ -156,7 +198,7 @@ hub.mode
156198

157199
hub.topic
158200
: _Required_ **string** - The URI of the GitHub repository to subscribe
159-
to. The path must be in the format of `/:user/:repo/events/push`.
201+
to. The path must be in the format of `/:user/:repo/events/:event`.
160202

161203
hub.callback
162204
: _Required_ **string** - The URI to receive the updates to the topic.

‎lib/resources.rb‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -645,13 +645,13 @@ def json(key)
645645
"updated_at" => "2011-09-06T20:39:23Z",
646646
"created_at" => "2011-09-06T17:26:27Z",
647647
"name" => "web",
648+
"events" => ["push"],
648649
"active" => true,
650+
"config" =>
651+
{'url' => 'http://example.com', 'content_type' => 'json'},
649652
"id" => 1
650653
}
651654

652-
FULL_HOOK = HOOK.merge 'config' =>
653-
{'url' => 'http://example.com', 'content_type' => 'json'}
654-
655655
end
656656
end
657657

0 commit comments

Comments
 (0)
0