Skip to content
Snippets Groups Projects
Verified Commit 253cc167 authored by Marcin Sedlak-Jakubowski's avatar Marcin Sedlak-Jakubowski :red_circle: Committed by GitLab
Browse files

CTRT: Edit Webhooks doc page structure

parent 01e2e257
No related branches found
No related tags found
1 merge request!165369CTRT: Edit Webhooks doc page structure
......@@ -157,7 +157,7 @@ If you cannot [provide GitLab with your Jenkins server URL and authentication in
1. Under **Secret Token**, select **Generate**.
1. Copy the token, and save the job configuration.
1. In GitLab:
- [Create a webhook for your project](../user/project/integrations/webhooks.md#configure-webhooks-in-gitlab).
- [Create a webhook for your project](../user/project/integrations/webhooks.md#configure-webhooks).
- Enter the trigger URL (such as `https://JENKINS_URL/project/YOUR_JOB`).
- Paste the token in **Secret Token**.
1. To test the webhook, select **Test**.
......
......@@ -189,7 +189,7 @@ an internal list of certificate authorities. The SSL certificate cannot
be self-signed.
You can disable SSL verification when you configure
[webhooks](webhooks.md#configure-webhooks-in-gitlab) and some integrations.
[webhooks](webhooks.md#configure-webhooks) and some integrations.
## Related topics
......
......@@ -49,7 +49,12 @@ specific to a group, including:
- [Group member events](webhook_events.md#group-member-events)
- [Subgroup events](webhook_events.md#subgroup-events)
## Configure webhooks in GitLab
## Configure webhooks
Create and configure webhooks in GitLab to integrate with your project's workflow.
This section covers creating webhooks, securing sensitive information, adding custom headers, using templates, and
filtering events. Use these options to set up webhooks that meet your specific requirements.
### Create a webhook
......@@ -172,9 +177,102 @@ You can filter push events by branch. Use one of the following options to filter
```
To configure branch filtering for a project or group, see
[Configure a webhook in GitLab](#configure-webhooks-in-gitlab)
[Configure a webhook in GitLab](#configure-webhooks)
### Configure webhooks to support mutual TLS
DETAILS:
**Offering:** Self-managed
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27450) in GitLab 16.9.
Prerequisites:
- You must be a GitLab administrator.
You can configure webhooks to support mutual TLS by configuring a client
certificate in PEM format. This certificate is set globally and
presented to the server during a TLS handshake. The certificate can also
be protected with a PEM passphrase.
To configure the certificate:
::Tabs
:::TabTitle Linux package (Omnibus)
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
```
1. Save the file and reconfigure GitLab:
```shell
sudo gitlab-ctl reconfigure
```
:::TabTitle Docker
1. Edit `docker-compose.yml`:
```yaml
version: "3.6"
services:
gitlab:
image: 'gitlab/gitlab-ee:latest'
restart: always
hostname: 'gitlab.example.com'
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
```
1. Save the file and restart GitLab:
```shell
docker compose up -d
```
:::TabTitle Self-compiled (source)
1. Edit `/home/git/gitlab/config/gitlab.yml`:
```yaml
production: &base
http_client:
tls_client_cert_file: '<PATH TO CLIENT PEM FILE>'
tls_client_cert_password: '<OPTIONAL PASSWORD>'
```
1. Save the file and restart GitLab:
```shell
# For systems running systemd
sudo systemctl restart gitlab.target
## View webhook request history
# For systems running SysV init
sudo service gitlab restart
```
::EndTabs
### Configuring firewalls for webhook traffic
When configuring firewalls for webhooks traffic, you can configure assuming that webhooks are usually sent asynchronously from Sidekiq nodes. However, there are cases
when webhooks are sent synchronously from Rails nodes, including when:
- [Testing a Webhook](#test-a-webhook) in the UI.
- [Retrying a Webhook](#inspect-request-and-response-details) in the UI.
## Manage webhooks
Monitor and maintain your configured webhooks in GitLab.
### View webhook request history
> - **Recent events** for group webhooks [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/325642) in GitLab 15.3.
......@@ -202,7 +300,7 @@ The table includes the following details about each request:
![Recent deliveries](img/webhook_logs.png)
### Inspect request and response details
#### Inspect request and response details
Prerequisites:
......@@ -227,7 +325,40 @@ To send the request again with the same data and the same [`Idempotency-Key` hea
If the webhook URL has changed, you cannot resend the request.
For resending programmatically, refer to our [API documentation](../../../api/project_webhooks.md#resend-a-project-webhook-event).
## Webhook receiver requirements
### Test a webhook
You can trigger a webhook manually, to ensure it's working properly. You can also send
a test request to re-enable a [disabled webhook](#re-enable-disabled-webhooks).
For example, to test `push events`, your project should have at least one commit. The webhook uses this commit in the webhook.
NOTE:
Testing is not supported for some types of events for project and groups webhooks.
For more information, see [issue 379201](https://gitlab.com/gitlab-org/gitlab/-/issues/379201).
Prerequisites:
- To test project webhooks, you must have at least the Maintainer role for the project.
- To test group webhooks, you must have the Owner role for the group.
To test a webhook:
1. In your project or group, on the left sidebar, select **Settings > Webhooks**.
1. Scroll down to the list of configured webhooks.
1. From the **Test** dropdown list, select the type of event to test.
You can also test a webhook from its edit page.
![Webhook testing](img/webhook_testing.png)
## Webhook reference
This section collects technical details about GitLab webhooks.
Use this information to better understand how webhooks work and integrate with your systems.
Refer to these specifics when setting up, troubleshooting, or optimizing your webhook configurations.
### Webhook receiver requirements
Webhook receiver endpoints should be fast and stable.
Slow and unstable receivers might be [disabled automatically](#auto-disabled-webhooks) to ensure system reliability.
......@@ -256,7 +387,7 @@ Endpoints should follow these best practices:
These responses might cause the webhook to be disabled automatically.
- Invalid HTTP responses are treated as failed requests.
## Auto-disabled webhooks
### Auto-disabled webhooks
> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/329849) for project webhooks in GitLab 15.7. Feature flag `web_hooks_disable_failed` removed.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385902) for group webhooks in GitLab 15.10.
......@@ -280,7 +411,7 @@ An auto-disabled webhook appears in the list of project or group webhooks as:
![Badges on failing webhooks](img/failed_badges.png)
### Temporarily disabled webhooks
#### Temporarily disabled webhooks
Project or group webhooks that return response codes in the `5xx` range
or experience a [timeout](../../../user/gitlab_com/index.md#webhooks) or other HTTP errors
......@@ -291,14 +422,14 @@ on each subsequent failure up to a maximum of 24 hours.
You can [re-enable temporarily disabled webhooks manually](#re-enable-disabled-webhooks)
if the webhook receiver no longer returns an error.
### Permanently disabled webhooks
#### Permanently disabled webhooks
Project or group webhooks that return response codes in the `4xx` range
are considered to be misconfigured and are permanently disabled.
These webhooks remain disabled until you [re-enable them manually](#re-enable-disabled-webhooks).
### Re-enable disabled webhooks
#### Re-enable disabled webhooks
> - Introduced in GitLab 15.2 [with a flag](../../../administration/feature_flags.md) named `webhooks_failed_callout`. Disabled by default.
> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/365535) in GitLab 15.7. Feature flag `webhooks_failed_callout` removed.
......@@ -307,33 +438,7 @@ To re-enable a temporarily or permanently disabled webhook manually, [send a tes
The webhook is re-enabled if the test request returns a response code in the `2xx` range.
## Test a webhook
You can trigger a webhook manually, to ensure it's working properly. You can also send
a test request to re-enable a [disabled webhook](#re-enable-disabled-webhooks).
For example, to test `push events`, your project should have at least one commit. The webhook uses this commit in the webhook.
NOTE:
Testing is not supported for some types of events for project and groups webhooks.
For more information, see [issue 379201](https://gitlab.com/gitlab-org/gitlab/-/issues/379201).
Prerequisites:
- To test project webhooks, you must have at least the Maintainer role for the project.
- To test group webhooks, you must have the Owner role for the group.
To test a webhook:
1. In your project or group, on the left sidebar, select **Settings > Webhooks**.
1. Scroll down to the list of configured webhooks.
1. From the **Test** dropdown list, select the type of event to test.
You can also test a webhook from its edit page.
![Webhook testing](img/webhook_testing.png)
## Delivery headers
### Delivery headers
> - `X-Gitlab-Event-UUID` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329743) in GitLab 14.8.
> - `X-Gitlab-Instance` header [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31333) in GitLab 15.5.
......@@ -351,7 +456,44 @@ Webhook requests to your endpoint include the following headers:
| `X-Gitlab-Event-UUID` | Unique ID per webhook that is not recursive. A hook is recursive if triggered by an earlier webhook that hit the GitLab instance. Recursive webhooks have the same value for this header. | `"13792a34-cac6-4fda-95a8-c58e00a3954e"` |
| `Idempotency-Key` | Unique ID that remains consistent across webhook retries. Use this header to ensure idempotency of webhook effects on integrations. | `"f5e5f430-f57b-4e6e-9fac-d9128cd7232f"` |
## Debug webhooks
### How image URLs are displayed in the webhook body
Relative image references are rewritten to use an absolute URL
in the body of a webhook.
For example, if an image, merge request, comment, or wiki page includes the
following image reference:
```markdown
![image](/uploads/$sha/image.png)
```
If:
- GitLab is installed at `gitlab.example.com`.
- The project is at `example-group/example-project`.
The reference is rewritten in the webhook body as follows:
```markdown
![image](https://gitlab.example.com/example-group/example-project/uploads/$sha/image.png)
```
Image URLs are not rewritten if:
- They already point to HTTP, HTTPS, or
protocol-relative URLs.
- They use advanced Markdown features like link labels.
## Related topics
- [Webhook events and webhook JSON payloads](webhook_events.md)
- [Project webhooks API](../../../api/project_webhooks.md)
- [Group webhooks API](../../../api/group_webhooks.md)
- [System hooks API](../../../api/system_hooks.md)
## Troubleshooting
### Debug webhooks
To debug GitLab webhooks and capture payloads, you can use:
......@@ -363,7 +505,7 @@ To debug GitLab webhooks and capture payloads, you can use:
For information about webhook events and the JSON data sent in the webhook payload,
see [webhook events](webhook_events.md).
### Public webhook inspection and testing tools
#### Public webhook inspection and testing tools
You can use public tools to inspect and test webhook payloads. These tools act as catch-all endpoints for HTTP requests and respond with a `200 OK` HTTP status code. You can use these payloads to develop your webhook services.
......@@ -377,11 +519,11 @@ These public tools include:
- [Webhook.site](https://webhook.site) to review incoming payloads
- [Webhook Tester](https://webhook-test.com) to inspect and debug incoming payloads
### GitLab Development Kit (GDK)
#### GitLab Development Kit (GDK)
For a safer development environment, you can use the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit) to develop against GitLab webhooks locally. With the GDK, you can send webhooks from your local GitLab instance to a webhook receiver running locally on your machine. To use this approach, you must install and configure the GDK.
### Create a private webhook receiver
#### Create a private webhook receiver
Prerequisites:
......@@ -414,7 +556,7 @@ To create a private webhook receiver:
ruby print_http_body.rb 8000
```
1. In GitLab, [configure the webhook](#configure-webhooks-in-gitlab) and add your
1. In GitLab, [configure the webhook](#configure-webhooks) and add your
receiver's URL (for example, `http://receiver.example.com:8000/`).
1. Select **Test**. You should see a similar message in the console:
......@@ -426,132 +568,6 @@ To create a private webhook receiver:
To add this receiver, you might have to [allow requests to the local network](../../../security/webhooks.md).
## How image URLs are displayed in the webhook body
Relative image references are rewritten to use an absolute URL
in the body of a webhook.
For example, if an image, merge request, comment, or wiki page includes the
following image reference:
```markdown
![image](/uploads/$sha/image.png)
```
If:
- GitLab is installed at `gitlab.example.com`.
- The project is at `example-group/example-project`.
The reference is rewritten in the webhook body as follows:
```markdown
![image](https://gitlab.example.com/example-group/example-project/uploads/$sha/image.png)
```
Image URLs are not rewritten if:
- They already point to HTTP, HTTPS, or
protocol-relative URLs.
- They use advanced Markdown features like link labels.
## Configure webhooks to support mutual TLS
DETAILS:
**Offering:** Self-managed
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27450) in GitLab 16.9.
Prerequisites:
- You must be a GitLab administrator.
You can configure webhooks to support mutual TLS by configuring a client
certificate in PEM format. This certificate is set globally and
presented to the server during a TLS handshake. The certificate can also
be protected with a PEM passphrase.
To configure the certificate:
::Tabs
:::TabTitle Linux package (Omnibus)
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
```
1. Save the file and reconfigure GitLab:
```shell
sudo gitlab-ctl reconfigure
```
:::TabTitle Docker
1. Edit `docker-compose.yml`:
```yaml
version: "3.6"
services:
gitlab:
image: 'gitlab/gitlab-ee:latest'
restart: always
hostname: 'gitlab.example.com'
environment:
GITLAB_OMNIBUS_CONFIG: |
gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
```
1. Save the file and restart GitLab:
```shell
docker compose up -d
```
:::TabTitle Self-compiled (source)
1. Edit `/home/git/gitlab/config/gitlab.yml`:
```yaml
production: &base
http_client:
tls_client_cert_file: '<PATH TO CLIENT PEM FILE>'
tls_client_cert_password: '<OPTIONAL PASSWORD>'
```
1. Save the file and restart GitLab:
```shell
# For systems running systemd
sudo systemctl restart gitlab.target
# For systems running SysV init
sudo service gitlab restart
```
::EndTabs
## Configuring firewalls for webhook traffic
When configuring firewalls for webhooks traffic, you can configure assuming that webhooks are usually sent asynchronously from Sidekiq nodes. However, there are cases
when webhooks are sent synchronously from Rails nodes, including when:
- [Testing a Webhook](#test-a-webhook) in the UI.
- [Retrying a Webhook](#inspect-request-and-response-details) in the UI.
## Related topics
- [Webhook events and webhook JSON payloads](webhook_events.md)
- [Project webhooks API](../../../api/project_webhooks.md)
- [Group webhooks API](../../../api/group_webhooks.md)
- [System hooks API](../../../api/system_hooks.md)
## Troubleshooting
### `unable to get local issuer certificate`
When SSL verification is enabled, you might get an error that GitLab
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment