Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings
This repository was archived by the owner on Nov 1, 2017. It is now read-only.

Commit3131e79

Browse files
committed
Merge pull request#428 from github/update-hooks
Merge master
2 parents93df80a +c561acd commit3131e79

File tree

14 files changed

+561
-33
lines changed

14 files changed

+561
-33
lines changed

‎Rules‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,13 @@ compile '/guides/*' do
5353
layoutitem[:layout] ||'guides'
5454
end
5555

56+
compile'/webhooks/*'do
57+
filter:kramdown,:toc_levels=>[2]
58+
filter:erb
59+
filter:colorize_syntax,:default_colorizer=>:pygmentsrb
60+
layoutitem[:layout] ||'webhooks'
61+
end
62+
5663
compile'*'do
5764
filter:erb
5865
filter:kramdown,:toc_levels=>[2]

‎content/v3/repos/deployments.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ deployment.
3838

3939
Deployments and Deployment Statuses both have associated
4040
[repository events](/v3/activity/events/types/#deploymentevent) when
41-
they're created. This allowsweb hooks and 3rd party integrations to respond to
41+
they're created. This allowswebhooks and 3rd party integrations to respond to
4242
deployment requests as well as update the status of a deployment as progress is
4343
made.
4444

‎content/v3/repos/hooks.md‎

Lines changed: 23 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,52 @@
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 RepositoryHooks 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)
10+
The RepositoryWebhooks 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)
1212
and the[PubSubHubbub API](#pubsubhubbub).
1313

14-
Each hook can be configured for a specific[service](#services) and one or
14+
Each hook can be configured for a specific[service](#services) and one or
1515
more[events](#events), regardless of the API used to do so.
1616

1717
##Services
1818

1919
A service is basically the name used to refer to a hook that has configuration
2020
settings, a list of available events, and default events.
2121

22-
>For instance, the
22+
>For instance, the
2323
[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`
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`
2626
event by default and supports the`public` event type as well.
2727

2828
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
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
3434
[events](#events).
3535

3636
Documentation for all available service hooks can be found in the
3737
[docs directory](https://github.com/github/github-services/tree/master/docs)
3838
of the github-services repository. A JSON representation of their names,
39-
default events, supported events, and configuration options can be seen
39+
default events, supported events, and configuration options can be seen
4040
at[api.github.com/hooks](https://api.github.com/hooks).
4141

4242

43-
##Events
43+
##Events
4444

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
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
4747
want to trigger.
4848

49-
For example, the
49+
For example, the
5050
[Web](https://github.com/github/github-services/blob/master/lib/services/web.rb)
5151
service listens for all events, while the
5252
[IRC](https://github.com/github/github-services/blob/master/lib/services/irc.rb)
@@ -80,13 +80,13 @@ Name | Description
8080

8181
The payloads for all hooks mirror[the payloads for the Event
8282
types](/v3/activity/events/types/), with the exception of[the original`push`
83-
event](http://help.github.com/post-receive-hooks/),
83+
event](http://help.github.com/post-receive-hooks/),
8484
which has a more detailed payload.
8585

8686

8787
##JSON HTTP
8888

89-
The JSON HTTP API follows the same conventions as the rest of the
89+
The JSON HTTP API follows the same conventions as the rest of the
9090
[GitHub API](http://developer.github.com/v3/).
9191

9292
###List
@@ -113,7 +113,7 @@ The JSON HTTP API follows the same conventions as the rest of the
113113

114114
####Parameter
115115

116-
Name | Type | Description
116+
Name | Type | Description
117117
-----|------|--------------
118118
`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.)
119119
`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.
@@ -125,7 +125,7 @@ Name | Type | Description
125125
The["web" service hook](https://github.com/github/github-services/blob/master/lib/services/web.rb#L4-11)
126126
takes these fields in the`config`:
127127

128-
Name | Type | Description
128+
Name | Type | Description
129129
-----|------|--------------
130130
`url`|`string` |**Required**. The URL to which the payloads will be delivered.
131131
`content_type`|`string` | The media type used to serialize the payloads. Supported values:`json` and`form`. Default:`form`.
@@ -251,7 +251,7 @@ exists, it will be modified according to the request.
251251

252252
####Parameters
253253

254-
Name | Type | Description
254+
Name | Type | Description
255255
-----|------|--------------
256256
``hub.mode``|`string` |**Required**. Either`subscribe` or`unsubscribe`.
257257
``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`.

‎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 receiveWebHooks?
46+
##Why can't my server with SSL receiveWebhooks?
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`.
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title:Configuring Your Server | GitHub API
3+
layout:webhooks
4+
---
5+
6+
#Configuring Your Server
7+
8+
* TOC
9+
{:toc}
10+
11+
Now that our webhook is ready to deliver messages, we'll set up a basic Sinatra server
12+
to handle incoming payloads.
13+
14+
Recall that we specifically set our webhook URL to`http://localhost:4567/payload`.
15+
Since we're developing locally, we'll need to expose our local development environment
16+
to the Internet, so that GitHub can send out messages, and our local server can
17+
process them.
18+
19+
Note: you can download the complete source code for this project
20+
[from the platform-samples repo][platform samples].
21+
22+
##Using ngrok
23+
24+
First, we'll install a program to expose our local host to the Internet. We'll use
25+
ngrok to do this.[ngrok is a free download](https://ngrok.com/download) available
26+
for all major operating systems.
27+
28+
When you're done with that, you can expose your localhost by running`./ngrok 4567`
29+
on the command line. You should see a line that looks something like this:
30+
31+
#!bash
32+
Forwarding http://7e9ea9dc.ngrok.com -> 127.0.0.1:4567
33+
34+
Copy that funky`*.ngrok.com` URL! We're now going to go*back* to the Payload
35+
URL and pasting this server into that field. It should look something like`http://7e9ea9dc.ngrok.com/payload`.
36+
37+
By doing this, we've set ourselves up to expose our localhost at path`/payload`
38+
to the Internet.
39+
40+
##Writing the server
41+
42+
Now comes the fun part! We want out server to listen to`POST` requests, at`/payload`,
43+
because that's where we told GitHub our webhook URL was. Since ngrok is exposing
44+
our local environment, we don't need to set up a real server someone online, and
45+
can happily test out our code locally.
46+
47+
Let's set up a little Sinatra app to do something with the information. Our initial
48+
setup might look something like this:
49+
50+
#!ruby
51+
require 'sinatra'
52+
require 'json'
53+
54+
post '/payload' do
55+
push = JSON.parse(params[:payload])
56+
puts "I got some JSON: #{push.inspect}"
57+
end
58+
59+
(If you're unfamiliar with how Sinatra works, we recommend[reading the Sinatra guide][Sinatra guide].)
60+
61+
Start this server up.
62+
63+
Since we set up our webhook to listen to events dealing with`Issues`, go ahead
64+
and create a new Issue on the repository you're testing with. Once you create
65+
it, switch back to your terminal. You should see something like this in your output:
66+
67+
#!bash
68+
[adding-hooks]* ~/github/platform-samples/hooks/ruby/configuring-your-server $ ruby server.rb
69+
== Sinatra/1.4.4 has taken the stage on 4567 for development with backup from Thin
70+
>> Thin web server (v1.5.1 codename Straight Razor)
71+
>> Maximum connections set to 1024
72+
>> Listening on localhost:4567, CTRL+C to stop
73+
I got some JSON: {"action"=>"opened", "issue"=>{"url"=>"...
74+
75+
Success! You've successfully configured your server to listen to webhooks. Your
76+
server can now process this information any way you see fit. For example, if you
77+
were setting up a "real" web application, you might want to log some of the JSON
78+
output to a database.
79+
80+
For additional information on working with webhooks for fun and profit, head on
81+
over to the[Testing Webhooks](/hooks/testing) guide.
82+
83+
[platform samples]:https://github.com/github/platform-samples/tree/master/hooks/ruby/configuring-your-server
84+
[Sinatra]:http://www.sinatrarb.com/

‎content/webhooks/creating/index.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title:Creating Webhooks | GitHub API
3+
layout:webhooks
4+
---
5+
6+
#Creating Webhooks
7+
8+
* TOC
9+
{:toc}
10+
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.
18+
19+
Creating a webhook is a two-step process. You'll first need to set up how you want
20+
your webhook to behave through GitHub--what events should it listen to. After that,
21+
you'll set up your server to receive and manage the payload.
22+
23+
##Setting up a Webhook
24+
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**.
27+
28+
You'll be presented with a page that lists all the capabilities your webhook
29+
can take advantage of. We'll go through each of these below.
30+
31+
##Payload URL
32+
33+
This is the server endpoint that will receive the webhook payload.
34+
35+
Since we're developing locally for our tutorial, let's set it to`http://localhost:4567/payload`.
36+
We'll explain why in the[Configuring Your Server](/hooks/configuring/) docs.
37+
38+
##Payload version
39+
40+
Webhooks can deliver various[media types](/v3/media/) as defined by the GitHub API.
41+
Choose the one that best fits your needs. For this tutorial, the default format is fine.
42+
43+
##Events
44+
45+
Events are at the core of webhooks. These webhooks fire whenever a certain action is
46+
taken on the repository, which your server's payload URL intercepts and acts upon.
47+
48+
A full list of webhook events, and when they execute, can be found in[the webhooks API][hooks-api] reference.
49+
50+
Since our webhook is dealing with Issues in a repository, we'll click on**Issues**,
51+
and toggle the options there.
52+
53+
When you're finished, click on**Add webhook**. Phew! Now that the webhook is created,
54+
it's time to set up our local server to test the webhook. Head on over to
55+
[Configuring Your Server](/hooks/configuring/) to learn how to do that.
56+
57+
[hooks-api]:http://developer.github.com/v3/repos/hooks/#events

‎content/webhooks/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title:Webhooks | GitHub API
3+
layout:webhooks
4+
---
5+
6+
Every GitHub repository has the option to communicate with a web server whenever
7+
the repository is pushed to. These "webhooks" can be used to update an external
8+
issue tracker, trigger CI builds, update a backup mirror, or even deploy to your
9+
production server.
10+
11+
This section of the GitHub Developer Guide will instruct you on how to develop, configure,
12+
and test your first webhook.

‎content/webhooks/testing/index.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title:Testing Webhooks | GitHub API
3+
layout:webhooks
4+
---
5+
6+
#Testing Webhooks
7+
8+
* TOC
9+
{:toc}
10+
11+
Now that you've[configured your local server](/hooks/configuring/), you might
12+
be interested in pushing your code to the limits. To that end, GitHub's webhooks
13+
view provides some tooling for testing your deployed payloads.
14+
15+
16+
##Listing recent deliveries
17+
18+
Every webhook has its own "Recent Deliveries" section, which lists, at a glance
19+
whether a deployment was successful (green dot) or failed (red dot).
20+
21+
![Recent Deliveries view](/images/webhooks_recent_deliveries.png)
22+
23+
You can also identify when each delivery was attempted.
24+
25+
##Digging into results
26+
27+
By expanding an individual delivery, you'll be able to witness*precisely*
28+
what information GitHub is attempting to send to your server. This includes
29+
both the HTTP Request and Response.
30+
31+
###Request
32+
33+
The webhook delivery view provides information on which Headers were sent by GitHub.
34+
It also includes details about the JSON payload.
35+
36+
##Response
37+
38+
The response tab lists how your server replied once it received the payload from
39+
GitHub. This includes the status code, the headers, and any additional data
40+
within the response body.

‎layouts/guides.html‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,17 @@
22

33
<bodyclass="api">
44
<%= render 'header' %>
5-
5+
66
<divclass="sub-nav">
77
<h2><ahref="/v3/">API</a></h2>
8-
8+
99
<ul>
1010
<li><ahref="/v3/">Documentation</a></li>
1111
<li><ahref="/guides/"class="active">Guides</a></li>
1212
<li><ahref="/libraries/">Libraries</a></li>
1313
</ul>
1414
</div>
15-
15+
1616
<divid="wrapper">
1717
<divclass="content">
1818
<%= yield %>
@@ -29,14 +29,14 @@ <h2><a href="/v3/">API</a></h2>
2929
<li><h3><ahref="/guides/traversing-with-pagination/">Traversing with Pagination</a></h3></li>
3030
</ul>
3131
</div>
32-
32+
3333
<divclass="sidebar-module notice">
3434
<p>This website is a<ahref="https://github.com/github/developer.github.com"target="_blank">public GitHub repository</a>. Please help us by forking the project and adding to it.</p>
3535
</div>
3636
<divclass="sidebar-module api-status"><ahref="https://status.github.com"class="unknown">API Status</a></div>
3737
</div><!-- sidebar-shell -->
3838
</div><!-- #wrapper -->
39-
39+
4040
<%= render 'footer' %>
4141
</body>
4242
</html>

‎layouts/header.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<ulclass="nav">
66
<li><ahref="/"class="nav-overview">Overview</a></li>
77
<li><ahref="/v3/"class="nav-api">API</a></li>
8+
<li><ahref="/webhooks/"class="nav-webhooks">Webhooks</a></li>
89
<li><ahref="/changes/"class="nav-blog">Blog</a></li>
910
<li><ahref="https://github.com/contact">Support</a></li>
1011
<liid="search-container">

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp