Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

update hook docs to talk about Hook#events

  • Loading branch information...
commit 63502d1b4232156551d33ad8a91150cfdd1874fb 1 parent c3fb85a
@technoweenie technoweenie authored
Showing with 55 additions and 13 deletions.
  1. +52 −10 content/v3/repos/hooks.md
  2. +3 −3 lib/resources.rb
View
62 content/v3/repos/hooks.md
@@ -8,6 +8,30 @@ The Repository Hooks API manages the post-receive web and service hooks
for a repository. There are two main APIs to manage these hooks: a JSON
HTTP API, and [PubSubHubbub](#pubsubhubbub).
+Active hooks can be configured to trigger for one or more events.
+The default event is `push`. The available events are:
+
+* `push` - Any git push to a Repository.
+* `issues` - Any time an Issue is opened or closed.
+* `issue_comment` - Any time an Issue is commented on.
+* `commit_comment` - Any time a Commit is commented on.
+* `pull_request` - Any time a Pull Request is opend, closed, or
+ synchronized (updated due to a new push in the branch that the pull
+request is tracking).
+* `gollum` - Any time a Wiki page is updated.
+* `watch` - Any time a User watches the Repository.
+* `download` - Any time a Download is added to the Repository.
+* `fork` - Any time a Repository is forked.
+* `fork_apply` - Any time a patch is applied to the Repository from the
+ Fork Queue.
+* `member` - Any time a User is added as a collaborator to a
+ non-Organization Repository.
+* `public` - Any time a Repository changes from private to public.
+
+For a Hook to go through, the Hook needs to be configured to trigger for
+an event, and the Service has to listen to it. The Services are all
+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.
+
## List
GET /repos/:user/:repo/hooks
@@ -24,7 +48,7 @@ HTTP API, and [PubSubHubbub](#pubsubhubbub).
### Response
<%= headers 200 %>
-<%= json :full_hook %>
+<%= json :hook %>
## Create a hook
@@ -42,24 +66,26 @@ settings for this hook. These settings vary between the services and
are defined in the
[github-services](https://github.com/github/github-services) repo.
+events
+: _Optional_ **array** - Determines what events the hook is triggered
+for. Default: `["push"]`.
+
active
: _Optional_ **boolean** - Determines whether the hook is actually
triggered on pushes.
<%= json \
- :name => "campfire",
+ :name => "web",
:active => true,
:config => {
- :subdomain => 'github',
- :room => 'Commits',
- :token => 'abc123'}
+ :url => 'http://something.com/webhook'}
%>
### Response
<%= headers 201,
:Location => 'https://api.github.com/repos/user/repo/hooks/1' %>
-<%= json :full_hook %>
+<%= json :hook %>
### Edit a hook
@@ -73,10 +99,23 @@ See [/hooks](https://api.github.com/hooks) for the possible names.
config
: _Required_ **hash** - A Hash containing key/value pairs to provide
-settings for this hook. These settings vary between the services and
+settings for this hook. Modifying this will replace the entire config
+object. These settings vary between the services and
are defined in the
[github-services](https://github.com/github/github-services) repo.
+events
+: _Optional_ **array** - Determines what events the hook is triggered
+for. This replaces the entire array of events. Default: `["push"]`.
+
+add_events
+: _Optional_ **array** - Determines a list of events to be added to the
+list of events that the Hook triggers for.
+
+remove_events
+: _Optional_ **array** - Determines a list of events to be removed from the
+list of events that the Hook triggers for.
+
active
: _Optional_ **boolean** - Determines whether the hook is actually
triggered on pushes.
@@ -93,7 +132,7 @@ triggered on pushes.
### Response
<%= headers 200 %>
-<%= json :full_hook %>
+<%= json :hook %>
## Test a hook
@@ -118,7 +157,10 @@ repository.
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:
- https://github.com/:user/:repo/events/push
+ https://github.com/:user/:repo/events/:event
+
+The event can be any Event string that is listed at the top of this
+document.
The default format is what [existing post-receive hooks should
expect][post-receive]: A JSON body sent as the `payload` parameter in a
@@ -156,7 +198,7 @@ hub.mode
hub.topic
: _Required_ **string** - The URI of the GitHub repository to subscribe
-to. The path must be in the format of `/:user/:repo/events/push`.
+to. The path must be in the format of `/:user/:repo/events/:event`.
hub.callback
: _Required_ **string** - The URI to receive the updates to the topic.
View
6 lib/resources.rb
@@ -645,13 +645,13 @@ def json(key)
"updated_at" => "2011-09-06T20:39:23Z",
"created_at" => "2011-09-06T17:26:27Z",
"name" => "web",
+ "events" => ["push"],
"active" => true,
+ "config" =>
+ {'url' => 'http://example.com', 'content_type' => 'json'},
"id" => 1
}
- FULL_HOOK = HOOK.merge 'config' =>
- {'url' => 'http://example.com', 'content_type' => 'json'}
-
end
end
Please sign in to comment.
Something went wrong with that request. Please try again.