Merge pull request #84 from github/add-hook-info-to-guides · github/developer.github.com@9367650 · GitHub
Skip to content
This repository was archived by the owner on Nov 1, 2017. It is now read-only.

Commit 9367650

Browse files
gjtorikiangjtorikian
committed
Merge pull request #84 from github/add-hook-info-to-guides
Add hook info to guides
2 parents bf3d75b + 90c2c30 commit 9367650

21 files changed

Lines changed: 768 additions & 198 deletions

File tree

‎Rules‎

Lines changed: 7 additions & 0 deletions

‎changes/index.html‎

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

‎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/repos/deployments.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ the `description` would be the high level summary of what happened with the
3737
deployment.
3838

3939
Deployments and Deployment Statuses both have associated repository events when
40-
they're created. This allows web hooks and 3rd party integrations to respond to
40+
they're created. This allows webhooks and 3rd party integrations to respond to
4141
deployment requests as well as update the status of a deployment as progress is
4242
made.
4343

‎content/v3/repos/hooks.md‎

Lines changed: 36 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,53 @@
11
---
2-
title: Hooks | GitHub API
2+
title: Webhooks | GitHub API
33
---
44

5-
# Hooks
5+
# Webhooks
66

77
* TOC
88
{:toc}
99

10-
The Repository Hooks API allows repository admins to manage the post-receive
11-
hooks for a repository. Hooks can be managed using the [JSON HTTP API](#json-http)
12-
and the [PubSubHubbub API](#pubsubhubbub).
10+
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,
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

116-
Name | Type | Description
38+
Name | Type | Description
11739
-----|------|--------------
11840
`name`|`string` | **Required**. The name of the service that is being called. (See [/hooks](https://api.github.com/hooks) for the list of valid hook names.)
11941
`config`|`hash` | **Required**. Key/value pairs to provide settings for this hook. These settings vary between the services and are defined in the [github-services](https://github.com/github/github-services) repository. Booleans are stored internally as "1" for true, and "0" for false. Any JSON `true`/`false` values will be converted automatically.
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`:
12749

128-
Name | Type | Description
50+
Name | Type | Description
12951
-----|------|--------------
13052
`url`|`string` | **Required**. The URL to which the payloads will be delivered.
13153
`content_type`|`string` | The media type used to serialize the payloads. Supported values: `json` and `form`. Default: `form`.
@@ -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
@@ -251,7 +183,7 @@ exists, it will be modified according to the request.
251183

252184
#### Parameters
253185

254-
Name | Type | Description
186+
Name | Type | Description
255187
-----|------|--------------
256188
``hub.mode``|`string` | **Required**. Either `subscribe` or `unsubscribe`.
257189
``hub.topic``|`string` |**Required**. The URI of the GitHub repository to subscribe to. The path must be in the format of `/:owner/:repo/events/:event`.
@@ -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/v3/troubleshooting.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ in order to get more results.
3030
It's important to *not* try and guess the format of the pagination URL. Not every
3131
API call uses the same structure. Instead, extract the pagination information from
3232
[the Link Header](/v3/#pagination), which is sent with every request.
33-
33+
3434
## Can I get my rate limits bumped?
3535

3636
The GitHub API has a pretty lenient quota for rate limits, for your enjoyment and
@@ -43,8 +43,8 @@ In certain exceptional cases, we may temporarily bump your rate limit higher. Yo
4343
should be prepared to answer technical questions about your goal and your planned usage of the API. We may still choose not to bump your limit if we feel that you can achieve your wildest
4444
dreams with the current rate limit (but don't worry, we'll help you out).
4545

46-
## Why can't my server with SSL receive WebHooks?
46+
## Why can't my server with SSL receive Webhooks?
4747

4848
When we send events to your server, we attempt to negotiate either SSL version 2 or 3.
4949
If your server requires a specific SSL version and does not support SSL negotiation,
50-
you can specify a specific version within the [WebHook's config block](http://developer.github.com/v3/repos/hooks/#edit-a-hook). Include a parameter called `ssl_version`, with a value of either `2` or `3`.
50+
you can specify a specific version within the [webhook's config block](http://developer.github.com/v3/repos/hooks/#edit-a-hook). Include a parameter called `ssl_version`, with a value of either `2` or `3`.

‎content/webhooks/configuring/index.md‎

Lines changed: 84 additions & 0 deletions

0 commit comments

Comments
 (0)