|
| 1 | +--- |
| 2 | +title:Repo Hooks API v3 | developer.github.com |
| 3 | +--- |
| 4 | + |
| 5 | +#Repo Hooks API |
| 6 | + |
| 7 | +The Repository Hooks API manages the post-receive web and service hooks |
| 8 | +for a repository. There are two main APIs to manage these hooks: a JSON |
| 9 | +HTTP API, and[PubSubHubbub](#pubsubhubbub). |
| 10 | + |
| 11 | +##List |
| 12 | + |
| 13 | +GET /repos/:user/:repo/hooks |
| 14 | + |
| 15 | +###Response |
| 16 | + |
| 17 | +<%= headers 200,:pagination => true %> |
| 18 | +<%= json(:hook) { |h|[h] } %> |
| 19 | + |
| 20 | +##Get single hook |
| 21 | + |
| 22 | +GET /repos/:user/:repo/hooks/:id |
| 23 | + |
| 24 | +###Response |
| 25 | + |
| 26 | +<%= headers 200 %> |
| 27 | +<%= json:full_hook %> |
| 28 | + |
| 29 | +##Create a hook |
| 30 | + |
| 31 | +POST /repos/:user/:repo/hooks |
| 32 | + |
| 33 | +###Input |
| 34 | + |
| 35 | +name |
| 36 | +:_Required_**string** - The name of the service that is being called. |
| 37 | +See[/hooks](https://api.github.com/hooks) for the possible names. |
| 38 | + |
| 39 | +config |
| 40 | +:_Required_**hash** - A Hash containing key/value pairs to provide |
| 41 | +settings for this hook. These settings vary between the services and |
| 42 | +are defined in the |
| 43 | +[github-services](https://github.com/github/github-services) repo. |
| 44 | + |
| 45 | +active |
| 46 | +:_Optional_**boolean** - Determines whether the hook is actually |
| 47 | +triggered on pushes. |
| 48 | + |
| 49 | +<%= json\ |
| 50 | +:name => "campfire", |
| 51 | +:active => true, |
| 52 | +:config => { |
| 53 | +:subdomain => 'github', |
| 54 | +:room => 'Commits', |
| 55 | +:token => 'abc123'} |
| 56 | +%> |
| 57 | + |
| 58 | +###Response |
| 59 | + |
| 60 | +<%= headers 201, |
| 61 | +:Location => 'https://api.github.com/repos/user/repo/hooks/1' %> |
| 62 | +<%= json:full_hook %> |
| 63 | + |
| 64 | +###Edit a hook |
| 65 | + |
| 66 | +PATCH /repos/:user/:repo/hooks/:id |
| 67 | + |
| 68 | +###Input |
| 69 | + |
| 70 | +name |
| 71 | +:_Required_**string** - The name of the service that is being called. |
| 72 | +See[/hooks](https://api.github.com/hooks) for the possible names. |
| 73 | + |
| 74 | +config |
| 75 | +:_Required_**hash** - A Hash containing key/value pairs to provide |
| 76 | +settings for this hook. These settings vary between the services and |
| 77 | +are defined in the |
| 78 | +[github-services](https://github.com/github/github-services) repo. |
| 79 | + |
| 80 | +active |
| 81 | +:_Optional_**boolean** - Determines whether the hook is actually |
| 82 | +triggered on pushes. |
| 83 | + |
| 84 | +<%= json\ |
| 85 | +:name => "campfire", |
| 86 | +:active => true, |
| 87 | +:config => { |
| 88 | +:subdomain => 'github', |
| 89 | +:room => 'Commits', |
| 90 | +:token => 'abc123'} |
| 91 | +%> |
| 92 | + |
| 93 | +###Response |
| 94 | + |
| 95 | +<%= headers 200 %> |
| 96 | +<%= json:full_hook %> |
| 97 | + |
| 98 | +##Test a hook |
| 99 | + |
| 100 | +This will trigger the hook with the latest push to the current |
| 101 | +repository. |
| 102 | + |
| 103 | +POST /repos/:user/:repo/hooks/:id/test |
| 104 | + |
| 105 | +###Response |
| 106 | + |
| 107 | +<%= headers 204 %> |
| 108 | + |
| 109 | +##Delete a hook |
| 110 | + |
| 111 | +DELETE /repos/:user/:repo/hooks/:id |
| 112 | + |
| 113 | +###Response |
| 114 | + |
| 115 | +<%= headers 204 %> |
| 116 | + |
| 117 | +##PubSubHubbub |
| 118 | + |
| 119 | +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: |
| 120 | + |
| 121 | +https://github.com/:user/:repo/events/push |
| 122 | + |
| 123 | +The default format is what[existing post-receive hooks should |
| 124 | +expect][post-receive]: A JSON body sent as the`payload` parameter in a |
| 125 | +POST. You can also specify to receive the raw JSON body with either an |
| 126 | +`Accept` header, or a`.json` extension. |
| 127 | + |
| 128 | +Accept: application/json |
| 129 | +https://github.com/:user/:repo/events/push.json |
| 130 | + |
| 131 | +Callback URLs can use either the`http://` protocol, or`github://`. |
| 132 | +`github://` callbacks specify a GitHub service. |
| 133 | + |
| 134 | +# Send updates to postbin.org |
| 135 | +http://postbin.org/123 |
| 136 | + |
| 137 | +# Send updates to Campfire |
| 138 | +github://campfire?subdomain=github&room=Commits&token=abc123 |
| 139 | + |
| 140 | +The GitHub PubSubHubbub endpoint is:https://api.github.com/hub. A |
| 141 | +successful request with curl looks like: |
| 142 | + |
| 143 | +curl -u "user:password" -i \ |
| 144 | + https://api.github.com/hub \ |
| 145 | + -F "hub.mode=subscribe" \ |
| 146 | + -F "hub.topic=https://github.com/:user/:repo/events/push" \ |
| 147 | + -F "hub.callback=http://postbin.org/123" |
| 148 | + |
| 149 | +PubSubHubbub requests can be sent multiple times. If the hook already |
| 150 | +exists, it will be modified according to the request. |
| 151 | + |
| 152 | +###Parameters |
| 153 | + |
| 154 | +hub.mode |
| 155 | +:_Required_**string** - Either`subscribe` or`unsubscribe`. |
| 156 | + |
| 157 | +hub.topic |
| 158 | +:_Required_**string** - The URI of the GitHub repository to subscribe |
| 159 | +to. The path must be in the format of`/:user/:repo/events/push`. |
| 160 | + |
| 161 | +hub.callback |
| 162 | +:_Required_**string** - The URI to receive the updates to the topic. |
| 163 | + |
| 164 | +hub.secret |
| 165 | +:_Optional_**string** - A shared secret key that generates a SHA1 HMAC |
| 166 | +of the payload content. You can verify a push came from GitHub by |
| 167 | +comparing the received body with the contents of the`X-Hub-Signature` |
| 168 | +header. |
| 169 | + |
| 170 | +[pubsub]:http://code.google.com/p/pubsubhubbub/ |
| 171 | +[post-receive]:http://help.github.com/post-receive-hooks/ |
| 172 | + |