diff options
Diffstat (limited to 'doc/user/project/integrations/webhooks.md')
| -rw-r--r-- | doc/user/project/integrations/webhooks.md | 137 |
1 files changed, 91 insertions, 46 deletions
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 6a436c5093e..d8b51e8b777 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -1,18 +1,18 @@ --- stage: Create group: Ecosystem -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: 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 --- # Webhooks 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 +like pushes, issues or merge requests. GitLab sends a POST request with data to the webhook URL. -In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver) -to receive information from GitLab, and send it to another app, according to your needs. +You usually need to set up your own [webhook receiver](#example-webhook-receiver) +to receive information from GitLab and send it to another app, according to your requirements. We already have a [built-in receiver](slack.md) for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. @@ -31,10 +31,9 @@ update a backup mirror, or even deploy to your production server. They are available **per project** for GitLab Community Edition, and **per project and per group** for **GitLab Enterprise Edition**. -Navigate to the webhooks page by going to your project's -**Settings ➔ Webhooks**. +Navigate to the webhooks page at your project's **Settings > Webhooks**. -NOTE: **Note:** +NOTE: On GitLab.com, the [maximum number of webhooks and their size](../../../user/gitlab_com/index.md#webhooks) per project, and per group, is limited. ## Version history @@ -55,7 +54,7 @@ Starting from GitLab 11.2: ``) have their target URL changed to an absolute URL. See [image URL rewriting](#image-url-rewriting) for more details. -## Use-cases +## Possible uses for webhooks - You can set up a webhook in GitLab to send a notification to [Slack](https://api.slack.com/incoming-webhooks) every time a job fails. @@ -65,27 +64,29 @@ Starting from GitLab 11.2: ## Webhook endpoint tips -If you are writing your own endpoint (web server) that will receive -GitLab webhooks keep in mind the following things: +If you are writing your own endpoint (web server) to receive +GitLab webhooks, keep in mind the following: -- 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 send its HTTP response as fast as possible. If the response takes longer than + the configured timeout, GitLab decides the hook failed and retries it. For information on + customizing this timeout, see + [Webhook fails or multiple webhook requests are triggered](#webhook-fails-or-multiple-webhook-requests-are-triggered). - 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. + not do this then GitLab thinks the hook failed and retries 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 +If you specify a secret token, it is 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 +an internal list of Certificate Authorities. This means the certificate cannot be self-signed. You can turn this off in the webhook settings in your GitLab projects. @@ -108,15 +109,15 @@ Below are described the supported events. Triggered when you push to the repository except when pushing tags. -NOTE: **Note:** +NOTE: When more than 20 commits are pushed at once, the `commits` webhook -attribute will only contain the first 20 for performance reasons. Loading +attribute only contains 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. +present in the `commits` attribute, the `total_commits_count` attribute contains the actual total. Also, if a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) branches, this hook won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +branches, this hook isn't executed. **Request header**: @@ -203,9 +204,10 @@ X-Gitlab-Event: Push Hook Triggered when you create (or delete) tags to the repository. -NOTE: **Note:** +NOTE: If a single push includes changes for more than three (by default, depending on -[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) tags, this hook won't be executed. +[`push_event_hooks_limit` setting](../../../api/settings.md#list-of-settings-that-can-be-accessed-via-api-calls)) +tags, this hook is not executed. **Request header**: @@ -407,14 +409,15 @@ X-Gitlab-Event: Issue Hook } ``` -> **Note**: `assignee` and `assignee_id` keys are deprecated and now show the first assignee only. +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. +The note data is stored in `object_attributes` (for example, `note` or `noteable_type`). The +payload also includes information about the target of the comment. For example, +a comment on an issue includes the specific issue information under the `issue` key. Valid target types: - `commit` @@ -732,7 +735,8 @@ X-Gitlab-Event: Note Hook } ``` -> **Note**: `assignee_id` field is deprecated and now shows the first assignee only. +NOTE: +`assignee_id` field is deprecated and now shows the first assignee only. #### Comment on code snippet @@ -1358,6 +1362,38 @@ X-Gitlab-Event: Deployment Hook Note that `deployable_id` is the ID of the CI job. +### Member events + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/260347) in GitLab 13.7. + +Triggered when a user is added as a group member. + +**Request Header**: + +```plaintext +X-Gitlab-Event: Member Hook +``` + +**Request Body**: + +```json +{ + "created_at": "2020-12-11T04:57:22Z", + "updated_at": "2020-12-11T04:57:22Z", + "group_name": "webhook-test", + "group_path": "webhook-test", + "group_id": 100, + "user_username": "test_user", + "user_name": "Test User", + "user_email": "testuser@webhooktest.com", + "user_id": 64, + "group_access": "Guest", + "group_plan": null, + "expires_at": "2020-12-14T00:00:00Z", + "event_name": "user_add_to_group" +} +``` + ### Feature Flag events Triggered when a feature flag is turned on or off. @@ -1502,21 +1538,22 @@ its description:  ``` -It will appear in the webhook body as the below (assuming that GitLab is -installed at `gitlab.example.com`, and the project is at -`example-group/example-project`): +It appears in the webhook body as follows assuming that: + +- GitLab is installed at `gitlab.example.com`. +- The project is at `example-group/example-project`. ```markdown  ``` -This will not rewrite URLs that already are pointing to HTTP, HTTPS, or -protocol-relative URLs. It will also not rewrite image URLs using advanced +This doesn't rewrite URLs that already are pointing to HTTP, HTTPS, or +protocol-relative URLs. It also doesn't rewrite image URLs using advanced Markdown features, like link labels. ## Testing webhooks -You can trigger the webhook manually. Sample data from the project will be used. +You can trigger the webhook manually. Sample data from the project is used. > For example: for triggering `Push Events` your project should have at least one commit.  @@ -1528,29 +1565,36 @@ You can find records for last 2 days in "Recent Deliveries" section on the edit  -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. +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: **Note:** -If URL or secret token of the webhook were updated, data will be delivered to the new address. +NOTE: +If URL or secret token of the webhook were updated, data is delivered to the new address. -### Receiving duplicate or multiple webhook requests triggered by one event +### Webhook fails or multiple webhook requests are triggered -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. +When GitLab sends a webhook, it expects a response in 10 seconds by default. If it does not receive +one, it retries 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`: +If your webhooks are failing or you are receiving multiple requests, you can try changing the +default value. You can do this by uncommenting or adding the following setting to your +`/etc/gitlab/gitlab.rb` file: ```ruby gitlab_rails['webhook_timeout'] = 10 ``` -### Troubleshooting: "Unable to get local issuer certificate" +### Unable to get local issuer certificate When SSL verification is enabled, this error indicates that GitLab isn't able to verify the SSL certificate of the webhook endpoint. Typically, this is because the root certificate isn't issued by a trusted certification authority as @@ -1561,7 +1605,7 @@ Missing intermediate certificates are a common point of verification failure. ## Example webhook receiver -If you want to see GitLab's webhooks in action for testing purposes you can use +If you want to see GitLab 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. @@ -1581,7 +1625,7 @@ end server.start ``` -Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb +Pick an unused port (for example, `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/`. @@ -1594,5 +1638,6 @@ example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0 - -> / ``` -NOTE: **Note:** -You may need to [allow requests to the local network](../../../security/webhooks.md) for this receiver to be added. +NOTE: +You may need to [allow requests to the local network](../../../security/webhooks.md) for this +receiver to be added. |