more granular access to your repository hooks without allowing access to your

repository contents:

*`read:repo_hook` grants read access to hooks in public or private repositories.

*`write:repo_hook` grants readandwrite access to hooks in public or private repositories.

*`admin:repo_hook` grants read, write, and delete access to hooks in public or private repositories.

*`read:repo_hook` grants readand pingaccess to hooks in public or private repositories.

*`write:repo_hook` grants read, write,andping access to hooks in public or private repositories.

*`admin:repo_hook` grants read, write,ping,and delete access to hooks in public or private repositories.

As always, if you have any questions or feedback,[get in touch][contact].

---

kind: change

title: Ping Event for Webhooks

created_at: 2014-2-10

author_name: kdaigle

---

With the release of our [new webhook UI](#), we included a new

[ping event](/v3/repos/hooks/#ping-event) that webhooks will receive. When you

create a new webhook, we will send this event as an initial test of the webhook.

The ping is only informational, doesn't need to be responded to in a specific way,

and nothing bad will happen if you respond with an error. It's just a quick

"hello world" to let you know you set everything up correctly.

We also added a [ping endpoint](/v3/repos/hooks/#ping-a-hook) to the hooks API.

By using ping instead of [test](/v3/repos/hooks/#test-a-push-hook), you can ensure

you won't be limited by the `push` event requirement that the test endpoint has.

`delete_repo`| Grants access to delete adminable repositories.

`notifications`| Grants read access to a user's notifications.`repo` also provides this access.

`gist`| Grants write access to gists.

`read:repo_hook`| Grants read access to hooks in public or private repositories.

`write:repo_hook`| Grants readandwrite access to hooks in public or private repositories.

`admin:repo_hook`| Grants read, write, and delete access to hooks in public or private repositories.

`read:repo_hook`| Grants readand pingaccess to hooks in public or private repositories.

`write:repo_hook`| Grants read, write,andping access to hooks in public or private repositories.

`admin:repo_hook`| Grants read, write,ping,and delete access to hooks in public or private repositories.

NOTE: Your application can request the scopes in the initial redirection. You

can specify multiple scopes by separating them with a comma:

{:toc}

The Repository Webhooks 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).

hooks for a repository. Webhooks can be managed using the JSON HTTP API,

or the[PubSubHubbub API](#pubsubhubbub).

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`

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

[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

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

want to trigger.

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)

service can only listen for`push`,`issues`, and`pull_request` events.

The available events are:

Name | Description

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

`push` | Any git push to a Repository.**This is the default event.**

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

`create` | Any time a Repository, Branch, or Tag is created.

`delete` | Any time a Branch or Tag is deleted.

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

`pull_request_review_comment` | Any time a Commit is commented on while inside a Pull Request review (the Files Changed tab).

`gollum` | Any time a Wiki page is updated.

`watch` | Any time a User watches the Repository.

`release` | Any time a Release is published in the Repository.

`fork` | Any time a Repository is forked.

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

`team_add` | Any time a team is added or modified on a Repository.

`status` | Any time a Repository has a status update from the API

`deployment` | Any time a Repository has a new deployment created from the API.

`deployment_status` | Any time a deployment for the Repository has a status update from the API.

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/),

which has a more detailed payload.

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

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

<%= headers 200,:pagination => default_pagination_rels %>

<%= json(:hook) { |h|[h] } %>

<%= headers 200 %>

<%= json:hook %>

Name | Type | Description

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

`events`|`array` | Determines what events the hook is triggered for. Default:`["push"]`

`active`|`boolean` | Determines whether the hook is actually triggered on pushes.

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

takes these fields in the`config`:

:content_type => 'json'}

%>

<%= headers 201,

:Location => 'https://api.github.com/repos/user/repo/hooks/1' %>

<%= json:hook %>

Name | Type | Description

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

`active`|`boolean` | Determines whether the hook is actually triggered on pushes.

<%= json\

:active => true,

:add_events =>['pull_request']

%>

<%= headers 200 %>

<%= json:hook %>

This will trigger the hook with the latest push to the current

repository if the hook is subscribed to`push` events. If the

**Note**: Previously`/repos/:owner/:repo/hooks/:id/test`

<%= headers 204 %>

This will trigger a[ping event][ping-event-url] to be sent to the hook.

<%= headers 204 %>

<%= headers 204 %>

The event can be any[event](#events) string that is listed at the top of this

The event can be any[event][events-url] string that is listed at the top of this

document.

[ruby-secret]:https://github.com/github/github-services/blob/14f4da01ce29bc6a02427a9fbf37b08b141e81d9/lib/services/web.rb#L47-L50

[hub-signature]:https://github.com/github/github-services/blob/f3bb3dd780feb6318c42b2db064ed6d481b70a1f/lib/service/http_helper.rb#L77

[pshb-secret]:http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html#authednotify

[events-url]:/webhooks/#events

[ping-event-url]:/webhooks/#ping-event

layout:webhooks

* TOC

{:toc}

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.

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

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

can configure hooks programmatically[via the API](/v3/repos/hooks/).

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`

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

[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

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

want to trigger.

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)

service can only listen for`push`,`issues`, and`pull_request` events.

The available events are:

Name | Description

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

`push` | Any git push to a Repository.**This is the default event.**

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

`create` | Any time a Repository, Branch, or Tag is created.

`delete` | Any time a Branch or Tag is deleted.

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

`pull_request_review_comment` | Any time a Commit is commented on while inside a Pull Request review (the Files Changed tab).

`gollum` | Any time a Wiki page is updated.

`watch` | Any time a User watches the Repository.

`release` | Any time a Release is published in the Repository.

`fork` | Any time a Repository is forked.

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

`team_add` | Any time a team is added or modified on a Repository.

`status` | Any time a Repository has a status update from the API

`deployment` | Any time a Repository has a new deployment created from the API.

`deployment_status` | Any time a deployment for the Repository has a status update from the API.

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/),

which has a more detailed payload.

When you create a new webhook, we'll send you a simple`ping` event to let you

know you've set up the webhook correctly. This event isn't stored so it isn't

retrievable via the[Events API](/v3/activity/events/). You can trigger a`ping`

again by calling the[ping endpoint](#).

Key | Value |

----| ----- |

zen | Random string of GitHub zen |

hook_id | The ID of the webhook that triggered the ping |