Webhooks

the project.ssh_url key is deprecated in favor of the project.git_ssh_url key

the project.http_url key is deprecated in favor of the project.git_http_url key

Project webhooks allow you to trigger a URL if for example new code is pushed or
a new issue is created. You can configure webhooks to listen for specific events
like pushes, issues or merge requests. GitLab will send a POST request with data
to the webhook URL.

Webhooks can be used to update an external issue tracker, trigger CI jobs,
update a backup mirror, or even deploy to your production server.

Navigate to the webhooks page by going to your project's
Settings ➔ Integrations.

Webhook endpoint tips

If you are writing your own endpoint (web server) that will receive
GitLab webhooks keep in mind the following things:

Your endpoint should send its HTTP response as fast as possible. If
you wait too long, GitLab may decide the hook failed and retry it.

Your endpoint should ALWAYS return a valid HTTP response. If you do
not do this then GitLab will think the hook failed and retry it.
Most HTTP libraries take care of this for you automatically but if
you are writing a low-level hook this is important to remember.

GitLab ignores the HTTP status code returned by your endpoint.

Secret token

If you specify a secret token, it will be sent with the hook request in the
X-Gitlab-Token HTTP header. Your webhook endpoint can check that to verify
that the request is legitimate.

SSL verification

By default, the SSL certificate of the webhook endpoint is verified based on
an internal list of Certificate Authorities, which means the certificate cannot
be self-signed.

You can turn this off in the webhook settings in your GitLab projects.

Events

Below are described the supported events.

Push events

Triggered when you push to the repository except when pushing tags.

Note: When more than 20 commits are pushed at once, the commits web hook
attribute will only contain the first 20 for performance reasons. Loading
detailed commit data is expensive. Note that despite only 20 commits being
present in the commits attribute, the total_commits_count attribute will
contain the actual total.

Note: assignee and assignee_id keys are deprecated and now show the first assignee only.

Comment events

Triggered when a new comment is made on commits, merge requests, issues, and code snippets.
The note data will be stored in object_attributes (e.g. note, noteable_type). The
payload will also include information about the target of the comment. For example,
a comment on an issue will include the specific issue information under the issue key.
Valid target types:

Wiki Page events

Triggered when a wiki page is created, updated or deleted.

Request Header:

X-Gitlab-Event: Wiki Page Hook

Request Body:

{"object_kind":"wiki_page","user":{"name":"Administrator","username":"root","avatar_url":"http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80\u0026d=identicon"},"project":{"id":1,"name":"awesome-project","description":"This is awesome","web_url":"http://example.com/root/awesome-project","avatar_url":null,"git_ssh_url":"git@example.com:root/awesome-project.git","git_http_url":"http://example.com/root/awesome-project.git","namespace":"root","visibility_level":0,"path_with_namespace":"root/awesome-project","default_branch":"master","homepage":"http://example.com/root/awesome-project","url":"git@example.com:root/awesome-project.git","ssh_url":"git@example.com:root/awesome-project.git","http_url":"http://example.com/root/awesome-project.git"},"wiki":{"web_url":"http://example.com/root/awesome-project/wikis/home","git_ssh_url":"git@example.com:root/awesome-project.wiki.git","git_http_url":"http://example.com/root/awesome-project.wiki.git","path_with_namespace":"root/awesome-project.wiki","default_branch":"master"},"object_attributes":{"title":"Awesome","content":"awesome content goes here","format":"markdown","message":"adding an awesome page to the wiki","slug":"awesome","url":"http://example.com/root/awesome-project/wikis/awesome","action":"create"}}

Testing webhooks

You can trigger the webhook manually. Sample data from the project will be used.Sample data will take from the project.

For example: for triggering Push Events your project should have at least one commit.

Troubleshoot webhooks

Gitlab stores each perform of the webhook.
You can find records for last 2 days in "Recent Deliveries" section on the edit page of each webhook.

In this section you can see HTTP status code (green for 200-299 codes, red for the others, internal error for failed deliveries ), triggered event, a time when the event was called, elapsed time of the request.

If you need more information about execution, you can click View details link.
On this page, you can see data that GitLab sends (request headers and body) and data that it received (response headers and body).

From this page, you can repeat delivery with the same data by clicking Resend Request button.

Note: If URL or secret token of the webhook were updated, data will be delivered to the new address.

When GitLab sends a webhook it expects a response in 10 seconds (set default value). If it does not receive one, it'll retry the webhook.
If the endpoint doesn't send its HTTP response within those 10 seconds, GitLab may decide the hook failed and retry it.

If you are receiving multiple requests, you can try increasing the default value to wait for the HTTP response after sending the webhook
by uncommenting or adding the following setting to your /etc/gitlab/gitlab.rb:

gitlab_rails['webhook_timeout'] = 10

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. For the following script to
work you need to have Ruby installed.