layoutitem[:layout] ||'guides'

layoutitem[:layout] ||'webhooks'

Deployments and Deployment Statuses both have associated

[repository events](/v3/activity/events/types/#deploymentevent) when

they're created. This allowsweb hooks and 3rd party integrations to respond to

they're created. This allowswebhooks and 3rd party integrations to respond to

deployment requests as well as update the status of a deployment as progress is

made.

title:Hooks | GitHub API

title:Webhooks | GitHub API

* TOC

{:toc}

The RepositoryHooks API allows repository admins to manage the post-receive

hooks for a repository.Hooks can be managed using the[JSON HTTP API](#json-http)

The RepositoryWebhooks API allows repository admins to manage the post-receive

hooks for a repository.Webhooks can be managed using the[JSON HTTP API](#json-http)

and the[PubSubHubbub API](#pubsubhubbub).

Each hook can be configured for a specific[service](#services) and one or

Each hook can be configured for a specific[service](#services) and one or

more[events](#events), regardless of the API used to do so.

A service is basically the name used to refer to a hook that has configuration

settings, a list of available events, and default events.

[email](https://github.com/github/github-services/blob/master/lib/services/email.rb)

service is a built-in GitHub service that will send event[payloads](#payloads)

to, at most, two email addresses. It will trigger for the`push`

service is a built-in GitHub service that will send event[payloads](#payloads)

to, at most, two email addresses. It will trigger for the`push`

event by default and supports the`public` event type as well.

A number of services have been integrated through the open source

[github-services](https://github.com/github/github-services) project. When

creating a[hook](#create-a-hook), the`:name` parameter must refer to one of

these services. A generic

[Web](https://github.com/github/github-services/blob/master/lib/services/web.rb)

service is available that can configured to trigger for any of the available

[github-services](https://github.com/github/github-services) project. When

creating a[hook](#create-a-hook), the`:name` parameter must refer to one of

these services. A generic

[Web](https://github.com/github/github-services/blob/master/lib/services/web.rb)

service is available that can configured to trigger for any of the available

[events](#events).

Documentation for all available service hooks can be found in the

[docs directory](https://github.com/github/github-services/tree/master/docs)

of the github-services repository. A JSON representation of their names,

default events, supported events, and configuration options can be seen

default events, supported events, and configuration options can be seen

at[api.github.com/hooks](https://api.github.com/hooks).

Active hooks can be configured to trigger for one or more service supported

events. In other words, the service must support listening for the event you

Active hooks can be configured to trigger for one or more service supported

events. In other words, the service must support listening for the event you

want to trigger.

For example, the

For example, the

[Web](https://github.com/github/github-services/blob/master/lib/services/web.rb)

service listens for all events, while the

[IRC](https://github.com/github/github-services/blob/master/lib/services/irc.rb)

The payloads for all hooks mirror[the payloads for the Event

types](/v3/activity/events/types/), with the exception of[the original`push`

event](http://help.github.com/post-receive-hooks/),

event](http://help.github.com/post-receive-hooks/),

which has a more detailed payload.

The JSON HTTP API follows the same conventions as the rest of the

The JSON HTTP API follows the same conventions as the rest of the

[GitHub API](http://developer.github.com/v3/).

Name | Type | Description

Name | Type | Description

-----|------|--------------

`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.)

`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.

The["web" service hook](https://github.com/github/github-services/blob/master/lib/services/web.rb#L4-11)

takes these fields in the`config`:

Name | Type | Description

Name | Type | Description

-----|------|--------------

`url`|`string` |**Required**. The URL to which the payloads will be delivered.

`content_type`|`string` | The media type used to serialize the payloads. Supported values:`json` and`form`. Default:`form`.

Name | Type | Description

Name | Type | Description

-----|------|--------------

``hub.mode``|`string` |**Required**. Either`subscribe` or`unsubscribe`.

``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`.

It's important to*not* try and guess the format of the pagination URL. Not every

API call uses the same structure. Instead, extract the pagination information from

[the Link Header](/v3/#pagination), which is sent with every request.

The GitHub API has a pretty lenient quota for rate limits, for your enjoyment and

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

dreams with the current rate limit (but don't worry, we'll help you out).

When we send events to your server, we attempt to negotiate either SSL version 2 or 3.

If your server requires a specific SSL version and does not support SSL negotiation,

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`.

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`.

title:Configuring Your Server | GitHub API

layout:webhooks

* TOC

{:toc}

Now that our webhook is ready to deliver messages, we'll set up a basic Sinatra server

to handle incoming payloads.

Recall that we specifically set our webhook URL to`http://localhost:4567/payload`.

Since we're developing locally, we'll need to expose our local development environment

to the Internet, so that GitHub can send out messages, and our local server can

process them.

Note: you can download the complete source code for this project

[from the platform-samples repo][platform samples].

First, we'll install a program to expose our local host to the Internet. We'll use

ngrok to do this.[ngrok is a free download](https://ngrok.com/download) available

for all major operating systems.

When you're done with that, you can expose your localhost by running`./ngrok 4567`

on the command line. You should see a line that looks something like this:

Copy that funky`*.ngrok.com` URL! We're now going to go*back* to the Payload

URL and pasting this server into that field. It should look something like`http://7e9ea9dc.ngrok.com/payload`.

By doing this, we've set ourselves up to expose our localhost at path`/payload`

to the Internet.

Now comes the fun part! We want out server to listen to`POST` requests, at`/payload`,

because that's where we told GitHub our webhook URL was. Since ngrok is exposing

our local environment, we don't need to set up a real server someone online, and

can happily test out our code locally.

Let's set up a little Sinatra app to do something with the information. Our initial

setup might look something like this:

(If you're unfamiliar with how Sinatra works, we recommend[reading the Sinatra guide][Sinatra guide].)

Start this server up.

Since we set up our webhook to listen to events dealing with`Issues`, go ahead

and create a new Issue on the repository you're testing with. Once you create

it, switch back to your terminal. You should see something like this in your output:

Success! You've successfully configured your server to listen to webhooks. Your

server can now process this information any way you see fit. For example, if you

were setting up a "real" web application, you might want to log some of the JSON

output to a database.

For additional information on working with webhooks for fun and profit, head on

over to the[Testing Webhooks](/hooks/testing) guide.

[platform samples]:https://github.com/github/platform-samples/tree/master/hooks/ruby/configuring-your-server

[Sinatra]:http://www.sinatrarb.com/

title:Creating Webhooks | GitHub API

layout:webhooks

* TOC

{:toc}

At their core, webhooks are events generated by GitHub that deliver a payload of

information about activity in a repository. Webhooks can trigger across several

different actions. For example, you can fire a payload of information any time

a commit is made, a repository is forked, or an issue is created.

In this tutorial, our webhook will be responsible for listing out how popular our

repository is, based on the number of Issues it receives per day.

Creating a webhook is a two-step process. You'll first need to set up how you want

your webhook to behave through GitHub--what events should it listen to. After that,

you'll set up your server to receive and manage the payload.

To set up a webhook on GitHub, head over to the**Settings** page of your repository,

and click on**Webhooks & services**. After that, click on**Add webhook**.

You'll be presented with a page that lists all the capabilities your webhook

can take advantage of. We'll go through each of these below.

This is the server endpoint that will receive the webhook payload.

Since we're developing locally for our tutorial, let's set it to`http://localhost:4567/payload`.

We'll explain why in the[Configuring Your Server](/hooks/configuring/) docs.

Webhooks can deliver various[media types](/v3/media/) as defined by the GitHub API.

Choose the one that best fits your needs. For this tutorial, the default format is fine.

Events are at the core of webhooks. These webhooks fire whenever a certain action is

taken on the repository, which your server's payload URL intercepts and acts upon.

A full list of webhook events, and when they execute, can be found in[the webhooks API][hooks-api] reference.

Since our webhook is dealing with Issues in a repository, we'll click on**Issues**,

and toggle the options there.

When you're finished, click on**Add webhook**. Phew! Now that the webhook is created,

it's time to set up our local server to test the webhook. Head on over to

[Configuring Your Server](/hooks/configuring/) to learn how to do that.

[hooks-api]:http://developer.github.com/v3/repos/hooks/#events

title:Webhooks | GitHub API

layout:webhooks

Every GitHub repository has the option to communicate with a web server whenever

the repository is pushed to. These "webhooks" can be used to update an external

issue tracker, trigger CI builds, update a backup mirror, or even deploy to your

production server.

This section of the GitHub Developer Guide will instruct you on how to develop, configure,

and test your first webhook.

title:Testing Webhooks | GitHub API

layout:webhooks

* TOC

{:toc}

Now that you've[configured your local server](/hooks/configuring/), you might

be interested in pushing your code to the limits. To that end, GitHub's webhooks

view provides some tooling for testing your deployed payloads.

Every webhook has its own "Recent Deliveries" section, which lists, at a glance

whether a deployment was successful (green dot) or failed (red dot).


You can also identify when each delivery was attempted.

By expanding an individual delivery, you'll be able to witness*precisely*

what information GitHub is attempting to send to your server. This includes

both the HTTP Request and Response.

The webhook delivery view provides information on which Headers were sent by GitHub.

It also includes details about the JSON payload.

The response tab lists how your server replied once it received the payload from

GitHub. This includes the status code, the headers, and any additional data

within the response body.

<bodyclass="api">

<%= render 'header' %>

<divclass="sub-nav">

<h2><ahref="/v3/">API</a></h2>

<li><ahref="/v3/">Documentation</a></li>

<li><ahref="/guides/"class="active">Guides</a></li>

<li><ahref="/libraries/">Libraries</a></li>

<divid="wrapper">

<divclass="content">

<%= yield %>

<li><h3><ahref="/guides/traversing-with-pagination/">Traversing with Pagination</a></h3></li>

<divclass="sidebar-module notice">

<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>

<divclass="sidebar-module api-status"><ahref="https://status.github.com"class="unknown">API Status</a></div>

<%= render 'footer' %>

</html>

<ulclass="nav">

<li><ahref="/"class="nav-overview">Overview</a></li>

<li><ahref="/v3/"class="nav-api">API</a></li>

<li><ahref="/webhooks/"class="nav-webhooks">Webhooks</a></li>

<li><ahref="/changes/"class="nav-blog">Blog</a></li>

<li><ahref="https://github.com/contact">Support</a></li>

<liid="search-container">