21 KiB
stage | group | info | type |
---|---|---|---|
none | unassigned | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments | reference |
System hooks
Your GitLab instance can perform HTTP POST requests on the following events:
group_create
group_destroy
group_rename
key_create
key_destroy
project_create
project_destroy
project_rename
project_transfer
project_update
repository_update
user_add_to_group
user_add_to_team
user_create
user_destroy
user_failed_login
user_remove_from_group
user_remove_from_team
user_rename
user_update_for_group
user_update_for_team
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 (including name, description, and tags)
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
repository URL, you can just listen for project_rename
).
user_failed_login
is sent whenever a blocked user attempts to sign in and is
denied access.
System hooks can be used, for example, for logging or changing information in an LDAP server.
NOTE: We follow the same structure and deprecations as Webhooks for Push and Tag events, but we never display commits.
Create a system hook
To create a system hook:
- On the top bar, select Menu > Admin.
- On the left sidebar, select System Hooks.
- Provide the URL and Secret Token.
- Select the checkbox next to each Trigger you want to enable.
- Select Enable SSL verification, if desired.
- Click Add system hook.
Hooks request example
Request header:
X-Gitlab-Event: System Hook
Project created:
{
"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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"created_at": "2012-07-21T07:30:56Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "user_add_to_team",
"access_level": "Maintainer",
"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": "visibilitylevel|private"
}
Team Member Removed:
{
"created_at": "2012-07-21T07:30:56Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "user_remove_from_team",
"access_level": "Maintainer",
"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": "visibilitylevel|private"
}
Team Member Updated:
{
"created_at": "2012-07-21T07:30:56Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "user_update_for_team",
"access_level": "Maintainer",
"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": "visibilitylevel|private"
}
User created:
{
"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:
{
"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:
{
"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
is ldap_blocked
.
User renamed:
{
"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
{
"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
{
"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:
{
"created_at": "2012-07-21T07:30:54Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "group_create",
"name": "StoreCloud",
"path": "storecloud",
"group_id": 78
}
Group removed:
{
"created_at": "2012-07-21T07:30:54Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "group_destroy",
"name": "StoreCloud",
"path": "storecloud",
"group_id": 78
}
Group renamed:
{
"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,
"old_path": "old-name",
"old_full_path": "parent-group/old-name"
}
New Group Member:
{
"created_at": "2012-07-21T07:30:56Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "user_add_to_group",
"group_access": "Maintainer",
"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:
{
"created_at": "2012-07-21T07:30:56Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "user_remove_from_group",
"group_access": "Maintainer",
"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 Updated:
{
"created_at": "2012-07-21T07:30:56Z",
"updated_at": "2012-07-21T07:38:22Z",
"event_name": "user_update_for_group",
"group_access": "Maintainer",
"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:
{
"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": "Example User",
"email": "user@example.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:
{
"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
}
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
{
"object_kind": "merge_request",
"user": {
"id": 1,
"name": "Administrator",
"username": "root",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"email": "admin@example.com"
},
"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"
}
}
Repository Update events
Triggered only once when you push to the repository (including tags).
Request header:
X-Gitlab-Event: System Hook
Request body:
{
"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"]
}
Local requests in system hooks
Requests to local network by system hooks can be allowed or blocked by an administrator.