2014-09-02 18:07:02 +05:30
# System hooks
2018-03-17 18:26:18 +05:30
Your GitLab instance can perform HTTP POST requests on the following events:
- `project_create`
- `project_destroy`
- `project_rename`
- `project_transfer`
- `project_update`
- `user_add_to_team`
- `user_remove_from_team`
- `user_create`
- `user_destroy`
- `user_failed_login`
- `user_rename`
- `key_create`
- `key_destroy`
- `group_create`
- `group_destroy`
- `group_rename`
- `user_add_to_group`
- `user_remove_from_group`
The triggers for most of these are self-explanatory, but `project_update` and `project_rename` deserve some clarification: `project_update` is fired any time an attribute of a project is changed (name, description, tags, etc.) *unless* the `path` attribute is also changed. In that case, a `project_rename` is triggered instead (so that, for instance, if all you care about is the repo URL, you can just listen for `project_rename` ).
`user_failed_login` is sent whenever a **blocked** user attempts to login and denied access.
2014-09-02 18:07:02 +05:30
System hooks can be used, e.g. for logging or changing information in a LDAP server.
2016-06-02 11:05:42 +05:30
> **Note:**
>
> We follow the same structure from Webhooks for Push and Tag events, but we never display commits.
>
> Same deprecations from Webhooks are valid here.
2014-09-02 18:07:02 +05:30
## Hooks request example
2015-09-11 14:41:01 +05:30
**Request header**:
```
X-Gitlab-Event: System Hook
```
2014-09-02 18:07:02 +05:30
**Project created:**
```json
{
"created_at": "2012-07-21T07:30:54Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2014-09-02 18:07:02 +05:30
"event_name": "project_create",
"name": "StoreCloud",
"owner_email": "johnsmith@gmail.com",
"owner_name": "John Smith",
2015-04-26 12:48:37 +05:30
"path": "storecloud",
"path_with_namespace": "jsmith/storecloud",
2014-09-02 18:07:02 +05:30
"project_id": 74,
2018-03-17 18:26:18 +05:30
"project_visibility": "private"
2014-09-02 18:07:02 +05:30
}
```
**Project destroyed:**
```json
{
"created_at": "2012-07-21T07:30:58Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2014-09-02 18:07:02 +05:30
"event_name": "project_destroy",
"name": "Underscore",
"owner_email": "johnsmith@gmail.com",
"owner_name": "John Smith",
"path": "underscore",
"path_with_namespace": "jsmith/underscore",
"project_id": 73,
2018-03-17 18:26:18 +05:30
"project_visibility": "internal"
2014-09-02 18:07:02 +05:30
}
```
2016-01-14 18:37:52 +05:30
**Project renamed:**
```json
{
"created_at": "2012-07-21T07:30:58Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "project_rename",
"name": "Underscore",
"path": "underscore",
"path_with_namespace": "jsmith/underscore",
"project_id": 73,
"owner_name": "John Smith",
"owner_email": "johnsmith@gmail.com",
"project_visibility": "internal",
2018-03-17 18:26:18 +05:30
"old_path_with_namespace": "jsmith/overscore"
2016-01-14 18:37:52 +05:30
}
```
2018-03-17 18:26:18 +05:30
Note that `project_rename` is not triggered if the namespace changes.
Please refer to `group_rename` and `user_rename` for that case.
2016-01-14 18:37:52 +05:30
**Project transferred:**
```json
{
"created_at": "2012-07-21T07:30:58Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "project_transfer",
"name": "Underscore",
"path": "underscore",
"path_with_namespace": "scores/underscore",
"project_id": 73,
"owner_name": "John Smith",
"owner_email": "johnsmith@gmail.com",
"project_visibility": "internal",
2018-03-17 18:26:18 +05:30
"old_path_with_namespace": "jsmith/overscore"
2016-01-14 18:37:52 +05:30
}
```
2017-08-17 22:00:37 +05:30
**Project updated:**
```json
{
"created_at": "2012-07-21T07:30:54Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "project_update",
"name": "StoreCloud",
"owner_email": "johnsmith@gmail.com",
"owner_name": "John Smith",
"path": "storecloud",
"path_with_namespace": "jsmith/storecloud",
"project_id": 74,
2018-03-17 18:26:18 +05:30
"project_visibility": "private"
2017-08-17 22:00:37 +05:30
}
```
2014-09-02 18:07:02 +05:30
**New Team Member:**
```json
{
2015-10-24 18:46:33 +05:30
"created_at": "2012-07-21T07:30:56Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2015-10-24 18:46:33 +05:30
"event_name": "user_add_to_team",
2018-11-08 19:23:39 +05:30
"project_access": "Maintainer",
2015-10-24 18:46:33 +05:30
"project_id": 74,
"project_name": "StoreCloud",
"project_path": "storecloud",
"project_path_with_namespace": "jsmith/storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
2016-01-14 18:37:52 +05:30
"user_username": "johnsmith",
2015-10-24 18:46:33 +05:30
"user_id": 41,
2018-03-17 18:26:18 +05:30
"project_visibility": "private"
2014-09-02 18:07:02 +05:30
}
```
**Team Member Removed:**
```json
{
2015-10-24 18:46:33 +05:30
"created_at": "2012-07-21T07:30:56Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2015-10-24 18:46:33 +05:30
"event_name": "user_remove_from_team",
2018-11-08 19:23:39 +05:30
"project_access": "Maintainer",
2015-10-24 18:46:33 +05:30
"project_id": 74,
"project_name": "StoreCloud",
"project_path": "storecloud",
"project_path_with_namespace": "jsmith/storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
2016-01-14 18:37:52 +05:30
"user_username": "johnsmith",
2015-10-24 18:46:33 +05:30
"user_id": 41,
2018-03-17 18:26:18 +05:30
"project_visibility": "private"
2014-09-02 18:07:02 +05:30
}
```
**User created:**
```json
{
"created_at": "2012-07-21T07:44:07Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2014-09-02 18:07:02 +05:30
"email": "js@gitlabhq.com",
"event_name": "user_create",
"name": "John Smith",
2016-01-14 18:37:52 +05:30
"username": "js",
2014-09-02 18:07:02 +05:30
"user_id": 41
}
```
**User removed:**
```json
{
"created_at": "2012-07-21T07:44:07Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2014-09-02 18:07:02 +05:30
"email": "js@gitlabhq.com",
"event_name": "user_destroy",
"name": "John Smith",
2016-01-14 18:37:52 +05:30
"username": "js",
2014-09-02 18:07:02 +05:30
"user_id": 41
}
```
2015-04-26 12:48:37 +05:30
2018-03-17 18:26:18 +05:30
**User failed login:**
```json
{
"event_name": "user_failed_login",
"created_at": "2017-10-03T06:08:48Z",
"updated_at": "2018-01-15T04:52:06Z",
"name": "John Smith",
"email": "user4@example.com",
"user_id": 26,
"username": "user4",
"state": "blocked"
}
```
If the user is blocked via LDAP, `state` will be `ldap_blocked` .
**User renamed:**
```json
{
"event_name": "user_rename",
"created_at": "2017-11-01T11:21:04Z",
"updated_at": "2017-11-01T14:04:47Z",
"name": "new-name",
"email": "best-email@example.tld",
"user_id": 58,
"username": "new-exciting-name",
"old_username": "old-boring-name"
}
```
2015-04-26 12:48:37 +05:30
**Key added**
```json
{
"event_name": "key_create",
"created_at": "2014-08-18 18:45:16 UTC",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2015-04-26 12:48:37 +05:30
"username": "root",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC58FwqHUbebw2SdT7SP4FxZ0w+lAO/erhy2ylhlcW/tZ3GY3mBu9VeeiSGoGz8hCx80Zrz+aQv28xfFfKlC8XQFpCWwsnWnQqO2Lv9bS8V1fIHgMxOHIt5Vs+9CAWGCCvUOAurjsUDoE2ALIXLDMKnJxcxD13XjWdK54j6ZXDB4syLF0C2PnAQSVY9X7MfCYwtuFmhQhKaBussAXpaVMRHltie3UYSBUUuZaB3J4cg/7TxlmxcNd+ppPRIpSZAB0NI6aOnqoBCpimscO/VpQRJMVLr3XiSYeT6HBiDXWHnIVPfQc03OGcaFqOit6p8lYKMaP/iUQLm+pgpZqrXZ9vB john@localhost",
"id": 4
}
```
**Key removed**
```json
{
"event_name": "key_destroy",
"created_at": "2014-08-18 18:45:16 UTC",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2015-04-26 12:48:37 +05:30
"username": "root",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC58FwqHUbebw2SdT7SP4FxZ0w+lAO/erhy2ylhlcW/tZ3GY3mBu9VeeiSGoGz8hCx80Zrz+aQv28xfFfKlC8XQFpCWwsnWnQqO2Lv9bS8V1fIHgMxOHIt5Vs+9CAWGCCvUOAurjsUDoE2ALIXLDMKnJxcxD13XjWdK54j6ZXDB4syLF0C2PnAQSVY9X7MfCYwtuFmhQhKaBussAXpaVMRHltie3UYSBUUuZaB3J4cg/7TxlmxcNd+ppPRIpSZAB0NI6aOnqoBCpimscO/VpQRJMVLr3XiSYeT6HBiDXWHnIVPfQc03OGcaFqOit6p8lYKMaP/iUQLm+pgpZqrXZ9vB john@localhost",
"id": 4
}
```
**Group created:**
```json
{
"created_at": "2012-07-21T07:30:54Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2015-04-26 12:48:37 +05:30
"event_name": "group_create",
"name": "StoreCloud",
2018-03-17 18:26:18 +05:30
"owner_email": null,
"owner_name": null,
2015-04-26 12:48:37 +05:30
"path": "storecloud",
"group_id": 78
}
```
2018-03-17 18:26:18 +05:30
`owner_name` and `owner_email` are always `null` . Please see https://gitlab.com/gitlab-org/gitlab-ce/issues/39675.
2015-04-26 12:48:37 +05:30
**Group removed:**
```json
{
"created_at": "2012-07-21T07:30:54Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2015-04-26 12:48:37 +05:30
"event_name": "group_destroy",
"name": "StoreCloud",
2018-03-17 18:26:18 +05:30
"owner_email": null,
"owner_name": null,
2015-04-26 12:48:37 +05:30
"path": "storecloud",
"group_id": 78
}
```
2018-03-17 18:26:18 +05:30
`owner_name` and `owner_email` are always `null` . Please see https://gitlab.com/gitlab-org/gitlab-ce/issues/39675.
**Group renamed:**
```json
{
"event_name": "group_rename",
"created_at": "2017-10-30T15:09:00Z",
"updated_at": "2017-11-01T10:23:52Z",
"name": "Better Name",
"path": "better-name",
"full_path": "parent-group/better-name",
"group_id": 64,
"owner_name": null,
"owner_email": null,
"old_path": "old-name",
"old_full_path": "parent-group/old-name"
}
```
`owner_name` and `owner_email` are always `null` . Please see https://gitlab.com/gitlab-org/gitlab-ce/issues/39675.
2015-04-26 12:48:37 +05:30
**New Group Member:**
```json
{
"created_at": "2012-07-21T07:30:56Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2015-04-26 12:48:37 +05:30
"event_name": "user_add_to_group",
2018-11-08 19:23:39 +05:30
"group_access": "Maintainer",
2015-04-26 12:48:37 +05:30
"group_id": 78,
"group_name": "StoreCloud",
"group_path": "storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
2016-01-14 18:37:52 +05:30
"user_username": "johnsmith",
2015-04-26 12:48:37 +05:30
"user_id": 41
}
```
**Group Member Removed:**
```json
{
"created_at": "2012-07-21T07:30:56Z",
2016-01-14 18:37:52 +05:30
"updated_at": "2012-07-21T07:38:22Z",
2015-04-26 12:48:37 +05:30
"event_name": "user_remove_from_group",
2018-11-08 19:23:39 +05:30
"group_access": "Maintainer",
2015-04-26 12:48:37 +05:30
"group_id": 78,
"group_name": "StoreCloud",
"group_path": "storecloud",
"user_email": "johnsmith@gmail.com",
"user_name": "John Smith",
2016-01-14 18:37:52 +05:30
"user_username": "johnsmith",
2015-04-26 12:48:37 +05:30
"user_id": 41
}
```
2016-06-02 11:05:42 +05:30
## Push events
2017-09-10 17:25:29 +05:30
Triggered when you push to the repository, except when pushing tags.
It generates one event per modified branch.
2016-06-02 11:05:42 +05:30
**Request header**:
```
X-Gitlab-Event: System Hook
```
**Request body:**
```json
{
"event_name": "push",
"before": "95790bf891e76fee5e1747ab589903a6a1f80f22",
"after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
"ref": "refs/heads/master",
"checkout_sha": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
"user_id": 4,
"user_name": "John Smith",
"user_email": "john@example.com",
"user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80",
"project_id": 15,
"project":{
"name":"Diaspora",
"description":"",
"web_url":"http://example.com/mike/diaspora",
"avatar_url":null,
"git_ssh_url":"git@example.com:mike/diaspora.git",
"git_http_url":"http://example.com/mike/diaspora.git",
"namespace":"Mike",
"visibility_level":0,
"path_with_namespace":"mike/diaspora",
"default_branch":"master",
"homepage":"http://example.com/mike/diaspora",
"url":"git@example.com:mike/diaspora.git",
"ssh_url":"git@example.com:mike/diaspora.git",
"http_url":"http://example.com/mike/diaspora.git"
},
"repository":{
"name": "Diaspora",
"url": "git@example.com:mike/diaspora.git",
"description": "",
"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
},
2017-08-17 22:00:37 +05:30
"commits": [
{
"id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428",
"message": "Add simple search to projects in public area",
"timestamp": "2013-05-13T18:18:08+00:00",
"url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428",
"author": {
"name": "Dmitriy Zaporozhets",
"email": "dmitriy.zaporozhets@gmail.com"
}
}
],
"total_commits_count": 1
2016-06-02 11:05:42 +05:30
}
```
## Tag events
Triggered when you create (or delete) tags to the repository.
2017-09-10 17:25:29 +05:30
It generates one event per modified tag.
2016-06-02 11:05:42 +05:30
**Request header**:
```
X-Gitlab-Event: System Hook
```
**Request body:**
```json
{
"event_name": "tag_push",
"before": "0000000000000000000000000000000000000000",
"after": "82b3d5ae55f7080f1e6022629cdb57bfae7cccc7",
"ref": "refs/tags/v1.0.0",
"checkout_sha": "5937ac0a7beb003549fc5fd26fc247adbce4a52e",
"user_id": 1,
"user_name": "John Smith",
"user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80",
"project_id": 1,
"project":{
"name":"Example",
"description":"",
"web_url":"http://example.com/jsmith/example",
"avatar_url":null,
"git_ssh_url":"git@example.com:jsmith/example.git",
"git_http_url":"http://example.com/jsmith/example.git",
"namespace":"Jsmith",
"visibility_level":0,
"path_with_namespace":"jsmith/example",
"default_branch":"master",
"homepage":"http://example.com/jsmith/example",
"url":"git@example.com:jsmith/example.git",
"ssh_url":"git@example.com:jsmith/example.git",
"http_url":"http://example.com/jsmith/example.git"
},
"repository":{
"name": "Example",
"url": "ssh://git@example.com/jsmith/example.git",
"description": "",
"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
}
```
2018-03-17 18:26:18 +05:30
### Merge request events
Triggered when a new merge request is created, an existing merge request was
updated/merged/closed or a commit is added in the source branch.
**Request header**:
```
X-Gitlab-Event: System Hook
```
```json
{
"object_kind": "merge_request",
"user": {
"name": "Administrator",
"username": "root",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon"
},
"project": {
"name": "Example",
"description": "",
"web_url": "http://example.com/jsmith/example",
"avatar_url": null,
"git_ssh_url": "git@example.com:jsmith/example.git",
"git_http_url": "http://example.com/jsmith/example.git",
"namespace": "Jsmith",
"visibility_level": 0,
"path_with_namespace": "jsmith/example",
"default_branch": "master",
"ci_config_path": "",
"homepage": "http://example.com/jsmith/example",
"url": "git@example.com:jsmith/example.git",
"ssh_url": "git@example.com:jsmith/example.git",
"http_url": "http://example.com/jsmith/example.git"
},
"object_attributes": {
"id": 90,
"target_branch": "master",
"source_branch": "ms-viewport",
"source_project_id": 14,
"author_id": 51,
"assignee_id": 6,
"title": "MS-Viewport",
"created_at": "2017-09-20T08:31:45.944Z",
"updated_at": "2017-09-28T12:23:42.365Z",
"milestone_id": null,
"state": "opened",
"merge_status": "unchecked",
"target_project_id": 14,
"iid": 1,
"description": "",
"updated_by_id": 1,
"merge_error": null,
"merge_params": {
"force_remove_source_branch": "0"
},
"merge_when_pipeline_succeeds": false,
"merge_user_id": null,
"merge_commit_sha": null,
"deleted_at": null,
"in_progress_merge_commit_sha": null,
"lock_version": 5,
"time_estimate": 0,
"last_edited_at": "2017-09-27T12:43:37.558Z",
"last_edited_by_id": 1,
"head_pipeline_id": 61,
"ref_fetched": true,
"merge_jid": null,
"source": {
"name": "Awesome Project",
"description": "",
"web_url": "http://example.com/awesome_space/awesome_project",
"avatar_url": null,
"git_ssh_url": "git@example.com:awesome_space/awesome_project.git",
"git_http_url": "http://example.com/awesome_space/awesome_project.git",
"namespace": "root",
"visibility_level": 0,
"path_with_namespace": "awesome_space/awesome_project",
"default_branch": "master",
"ci_config_path": "",
"homepage": "http://example.com/awesome_space/awesome_project",
"url": "http://example.com/awesome_space/awesome_project.git",
"ssh_url": "git@example.com:awesome_space/awesome_project.git",
"http_url": "http://example.com/awesome_space/awesome_project.git"
},
"target": {
"name": "Awesome Project",
"description": "Aut reprehenderit ut est.",
"web_url": "http://example.com/awesome_space/awesome_project",
"avatar_url": null,
"git_ssh_url": "git@example.com:awesome_space/awesome_project.git",
"git_http_url": "http://example.com/awesome_space/awesome_project.git",
"namespace": "Awesome Space",
"visibility_level": 0,
"path_with_namespace": "awesome_space/awesome_project",
"default_branch": "master",
"ci_config_path": "",
"homepage": "http://example.com/awesome_space/awesome_project",
"url": "http://example.com/awesome_space/awesome_project.git",
"ssh_url": "git@example.com:awesome_space/awesome_project.git",
"http_url": "http://example.com/awesome_space/awesome_project.git"
},
"last_commit": {
"id": "ba3e0d8ff79c80d5b0bbb4f3e2e343e0aaa662b7",
"message": "fixed readme",
"timestamp": "2017-09-26T16:12:57Z",
"url": "http://example.com/awesome_space/awesome_project/commits/da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
"author": {
"name": "GitLab dev user",
"email": "gitlabdev@dv6700.(none)"
}
},
"work_in_progress": false,
"total_time_spent": 0,
"human_total_time_spent": null,
"human_time_estimate": null
},
"labels": null,
"repository": {
"name": "git-gpg-test",
"url": "git@example.com:awesome_space/awesome_project.git",
"description": "",
"homepage": "http://example.com/awesome_space/awesome_project"
}
}
```
2017-09-10 17:25:29 +05:30
## Repository Update events
Triggered only once when you push to the repository (including tags).
**Request header**:
```
X-Gitlab-Event: System Hook
```
**Request body:**
```json
{
"event_name": "repository_update",
"user_id": 1,
"user_name": "John Smith",
"user_email": "admin@example.com",
"user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80",
"project_id": 1,
"project": {
"name":"Example",
"description":"",
"web_url":"http://example.com/jsmith/example",
"avatar_url":null,
"git_ssh_url":"git@example.com:jsmith/example.git",
"git_http_url":"http://example.com/jsmith/example.git",
"namespace":"Jsmith",
"visibility_level":0,
"path_with_namespace":"jsmith/example",
"default_branch":"master",
"homepage":"http://example.com/jsmith/example",
"url":"git@example.com:jsmith/example.git",
"ssh_url":"git@example.com:jsmith/example.git",
"http_url":"http://example.com/jsmith/example.git",
},
"changes": [
{
"before":"8205ea8d81ce0c6b90fbe8280d118cc9fdad6130",
"after":"4045ea7a3df38697b3730a20fb73c8bed8a3e69e",
"ref":"refs/heads/master"
}
],
"refs":["refs/heads/master"]
}
```
