web_hooks.md 6.17 KB
Newer Older
Marin Jankovski's avatar
Marin Jankovski committed
1 2
# Web hooks

3
Project web hooks allow you to trigger an URL if new code is pushed or a new issue is created.
4

5
You can configure web hooks to listen for specific events like pushes, issues or merge requests. GitLab will send a POST request with data to the web hook URL.
6

7
Web hooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server.
8

9
If you send a web hook to an SSL endpoint [the certificate will not be verified](https://gitlab.com/gitlab-org/gitlab-ce/blob/ccd617e58ea71c42b6b073e692447d0fe3c00be6/app/models/web_hook.rb#L35) since many people use self-signed certificates.
10

11
## Push events
12

13
Triggered when you push to the repository except when pushing tags.
14 15 16 17 18 19 20 21 22 23 24 25 26

**Request body:**

```json
{
  "before": "95790bf891e76fee5e1747ab589903a6a1f80f22",
  "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
  "ref": "refs/heads/master",
  "user_id": 4,
  "user_name": "John Smith",
  "project_id": 15,
  "repository": {
    "name": "Diaspora",
27
    "url": "git@example.com:mike/diasporadiaspora.git",
28
    "description": "",
29 30 31 32
    "homepage": "http://example.com/mike/diaspora", 
    "git_http_url":"http://example.com/mike/diaspora.git",
    "git_ssh_url":"git@example.com:mike/diaspora.git",
    "visibility_level":0
33 34 35 36 37 38
  },
  "commits": [
    {
      "id": "b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327",
      "message": "Update Catalan translation to e38cb41.",
      "timestamp": "2011-12-12T14:27:31+02:00",
39
      "url": "http://example.com/mike/diaspora/commit/b6568db1bc1dcd7f8b4d5a946b0b91f9dacd7327",
40 41
      "author": {
        "name": "Jordi Mallach",
42
        "email": "jordi@softcatala.org"
43 44 45 46 47 48
      }
    },
    {
      "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
      "message": "fixed readme",
      "timestamp": "2012-01-03T23:36:29+02:00",
49
      "url": "http://example.com/mike/diaspora/commit/da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
50 51
      "author": {
        "name": "GitLab dev user",
52 53 54
        "email": "gitlabdev@dv6700.(none)"
      }
    }
55
  ],
56 57
  "total_commits_count": 4
}
58 59
```

60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
## Tag events

Triggered when you create (or delete) tags to the repository.

**Request body:**

```json
{
  "ref": "refs/tags/v1.0.0",
  "before": "0000000000000000000000000000000000000000",
  "after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7",
  "user_id": 1,
  "user_name": "John Smith",
  "project_id": 1,
  "repository": {
    "name": "jsmith",
    "url": "ssh://git@example.com/jsmith/example.git",
    "description": "",
78 79 80 81 82 83 84
    "homepage": "http://example.com/jsmith/example",
    "git_http_url":"http://example.com/jsmith/example.git",
    "git_ssh_url":"git@example.com:jsmith/example.git",
    "visibility_level":0
  },
  "commits": [],
  "total_commits_count": 0
85 86 87
}
```

88
## Issues events
89 90 91 92 93 94 95

Triggered when a new issue is created or an existing issue was updated/closed/reopened.

**Request body:**

```json
{
96
  "object_kind": "issue",
Kirill Zaitsev's avatar
Kirill Zaitsev committed
97 98 99 100 101
  "user": {
    "name": "Administrator",
    "username": "root",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
  },
102 103 104 105 106 107 108 109 110 111 112 113 114
  "object_attributes": {
    "id": 301,
    "title": "New API: create/update/delete file",
    "assignee_id": 51,
    "author_id": 51,
    "project_id": 14,
    "created_at": "2013-12-03T17:15:43Z",
    "updated_at": "2013-12-03T17:15:43Z",
    "position": 0,
    "branch_name": null,
    "description": "Create new API for manipulations with repository",
    "milestone_id": null,
    "state": "opened",
sue445's avatar
sue445 committed
115 116 117
    "iid": 23,
    "url": "http://example.com/diaspora/issues/23",
    "action": "open"
118 119 120 121
  }
}
```

122
## Merge request events
123

124
Triggered when a new merge request is created or an existing merge request was updated/merged/closed.
125 126 127 128 129

**Request body:**

```json
{
130
  "object_kind": "merge_request",
Kirill Zaitsev's avatar
Kirill Zaitsev committed
131 132 133 134 135
  "user": {
    "name": "Administrator",
    "username": "root",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon"
  },
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
  "object_attributes": {
    "id": 99,
    "target_branch": "master",
    "source_branch": "ms-viewport",
    "source_project_id": 14,
    "author_id": 51,
    "assignee_id": 6,
    "title": "MS-Viewport",
    "created_at": "2013-12-03T17:23:34Z",
    "updated_at": "2013-12-03T17:23:34Z",
    "st_commits": null,
    "st_diffs": null,
    "milestone_id": null,
    "state": "opened",
    "merge_status": "unchecked",
    "target_project_id": 14,
    "iid": 1,
Kirill Zaitsev's avatar
Kirill Zaitsev committed
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
    "description": "",
    "source": {
      "name": "awesome_project",
      "ssh_url": "ssh://git@example.com/awesome_space/awesome_project.git",
      "http_url": "http://example.com/awesome_space/awesome_project.git",
      "visibility_level": 20,
      "namespace": "awesome_space"
    },
    "target": {
      "name": "awesome_project",
      "ssh_url": "ssh://git@example.com/awesome_space/awesome_project.git",
      "http_url": "http://example.com/awesome_space/awesome_project.git",
      "visibility_level": 20,
      "namespace": "awesome_space"
    },
    "last_commit": {
      "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
      "message": "fixed readme",
      "timestamp": "2012-01-03T23:36:29+02:00",
      "url": "http://example.com/awesome_space/awesome_project/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
      "author": {
        "name": "GitLab dev user",
        "email": "gitlabdev@dv6700.(none)"
      }
177 178 179
    },
    "url": "http://example.com/diaspora/merge_requests/1",
    "action": "open"
180 181 182
  }
}
```
183 184 185 186 187 188 189 190 191 192 193

#### Example webhook receiver

If you want to see GitLab's webhooks in action for testing purposes you can use
a simple echo script running in a console session.

Save the following file as `print_http_body.rb`.

```ruby
require 'webrick'

194
server = WEBrick::HTTPServer.new(:Port => ARGV.first)
195 196 197 198
server.mount_proc '/' do |req, res|
  puts req.body
end

199 200 201
trap 'INT' do 
  server.shutdown 
end
202 203 204 205 206 207 208 209 210 211 212
server.start
```

Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb
8000`.  Then add your server as a webhook receiver in GitLab as
`http://my.host:8000/`.

When you press 'Test Hook' in GitLab, you should see something like this in the console.

```
{"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}
213
example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0
214 215
- -> /
```