# System hooks 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. System hooks can be used, e.g. for logging or changing information in a LDAP server. > **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. ## Hooks request example **Request header**: ``` X-Gitlab-Event: System Hook ``` **Project created:** ```json { "created_at": "2012-07-21T07:30:54Z", "updated_at": "2012-07-21T07:38:22Z", "event_name": "project_create", "name": "StoreCloud", "owner_email": "johnsmith@gmail.com", "owner_name": "John Smith", "path": "storecloud", "path_with_namespace": "jsmith/storecloud", "project_id": 74, "project_visibility": "private" } ``` **Project destroyed:** ```json { "created_at": "2012-07-21T07:30:58Z", "updated_at": "2012-07-21T07:38:22Z", "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, "project_visibility": "internal" } ``` **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", "old_path_with_namespace": "jsmith/overscore" } ``` Note that `project_rename` is not triggered if the namespace changes. Please refer to `group_rename` and `user_rename` for that case. **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", "old_path_with_namespace": "jsmith/overscore" } ``` **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, "project_visibility": "private" } ``` **New Team Member:** ```json { "created_at": "2012-07-21T07:30:56Z", "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_add_to_team", "project_access": "Master", "project_id": 74, "project_name": "StoreCloud", "project_path": "storecloud", "project_path_with_namespace": "jsmith/storecloud", "user_email": "johnsmith@gmail.com", "user_name": "John Smith", "user_username": "johnsmith", "user_id": 41, "project_visibility": "private" } ``` **Team Member Removed:** ```json { "created_at": "2012-07-21T07:30:56Z", "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_remove_from_team", "project_access": "Master", "project_id": 74, "project_name": "StoreCloud", "project_path": "storecloud", "project_path_with_namespace": "jsmith/storecloud", "user_email": "johnsmith@gmail.com", "user_name": "John Smith", "user_username": "johnsmith", "user_id": 41, "project_visibility": "private" } ``` **User created:** ```json { "created_at": "2012-07-21T07:44:07Z", "updated_at": "2012-07-21T07:38:22Z", "email": "js@gitlabhq.com", "event_name": "user_create", "name": "John Smith", "username": "js", "user_id": 41 } ``` **User removed:** ```json { "created_at": "2012-07-21T07:44:07Z", "updated_at": "2012-07-21T07:38:22Z", "email": "js@gitlabhq.com", "event_name": "user_destroy", "name": "John Smith", "username": "js", "user_id": 41 } ``` **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" } ``` **Key added** ```json { "event_name": "key_create", "created_at": "2014-08-18 18:45:16 UTC", "updated_at": "2012-07-21T07:38:22Z", "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", "updated_at": "2012-07-21T07:38:22Z", "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", "updated_at": "2012-07-21T07:38:22Z", "event_name": "group_create", "name": "StoreCloud", "owner_email": null, "owner_name": null, "path": "storecloud", "group_id": 78 } ``` `owner_name` and `owner_email` are always `null`. Please see https://gitlab.com/gitlab-org/gitlab-ce/issues/39675. **Group removed:** ```json { "created_at": "2012-07-21T07:30:54Z", "updated_at": "2012-07-21T07:38:22Z", "event_name": "group_destroy", "name": "StoreCloud", "owner_email": null, "owner_name": null, "path": "storecloud", "group_id": 78 } ``` `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. **New Group Member:** ```json { "created_at": "2012-07-21T07:30:56Z", "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_add_to_group", "group_access": "Master", "group_id": 78, "group_name": "StoreCloud", "group_path": "storecloud", "user_email": "johnsmith@gmail.com", "user_name": "John Smith", "user_username": "johnsmith", "user_id": 41 } ``` **Group Member Removed:** ```json { "created_at": "2012-07-21T07:30:56Z", "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_remove_from_group", "group_access": "Master", "group_id": 78, "group_name": "StoreCloud", "group_path": "storecloud", "user_email": "johnsmith@gmail.com", "user_name": "John Smith", "user_username": "johnsmith", "user_id": 41 } ``` ## Push events Triggered when you push to the repository, except when pushing tags. It generates one event per modified branch. **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 }, "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 } ``` ## Tag events Triggered when you create (or delete) tags to the repository. It generates one event per modified tag. **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 } ``` ## 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"] } ```