+++
title = "Webhook server"
weight = 7
+++
# Webhook server
By default `gw` checks for updates every minute. Depending on your usecase it can be too slow or too often. If you only want to pull updates when a push happens, git servers (GitHub, GitLab or any other) usually have options to send a HTTP request to your `gw` service (webhook). `gw` can handle webhooks with a built-in web server.
## Usage
To enable the webhook server, you can use the `--http` option. Most of the time you want to allow external connections, so to set to a high port (for example `10101`), you can use:
```sh
gw /path/to/repo -v --http 0.0.0.0:10101
```
If you call this endpoint with any method on any URL, it will trigger a check for updates. To test this, you can use `curl`:
```sh
curl http://localhost:10101
```
The `curl` output should print `OK` and the `gw` logs should include lines that show that it was updated:
```sh
$ gw /path/to/repo -v --http 0.0.0.0:10101
# ...
2024-03-10T16:52:51.531Z [DEBUG] Received request on GET /
2024-03-10T16:52:52.055Z [DEBUG] Checked out 5e25714 on branch main.
2024-03-10T16:52:52.055Z [INFO ] There are updates, pulling.
```
### Using only webhooks
If you want to disable the scheduled checks altogether and rely on the webhooks, you can set the schedule duration (`-d` flag) to zero seconds:
```sh
gw /path/to/repo -v --http 0.0.0.0:10101 -d 0s
```
You can use this to create a push-based deployment, for example calling the update from your CI process after your testing has run.
## Setup webhooks
Exposing a port is only one half of the problem, you also have to set the webhooks up with your git server. For this you will need a public IP or a domain name, which will be in the `$DOMAIN` variable in these examples.
> **Warning:** if you can configure, you should setup your reverse proxy in front of the port to avoid exposing externally.
### GitHub
For GitHub, you have to have administrator access to the repository. Navigate to **Settings > Webhooks**, and click to **Add webhook**. Fill the **Payload URL** with your `$DOMAIN` (make sure to add the `http://` protocol and the port) and select **application/json** for **Content Type**. Save this webhook to activate.
> **Note**: Secrets are currently not supported.
On save, the webhook should send a `ping` event to `gw`. If you click into new webhook, to **Recent deliveries** you can see this event.
A `POST /` request will also appear in the `gw` logs, assuming debug logging was enabled:
```sh
$ gw /path/to/repo -v --http 0.0.0.0:10101
# ...
2024-03-10T17:18:24.424Z [DEBUG] Received request on POST /
2024-03-10T17:18:24.567Z [DEBUG] There are no updates.
```
### GitLab
For GitLab, you have to have Maintainer access to the repository. Navigate to **Settings > Webhooks**, and click to **Add new webhook**. Fill the **URL** with your `$DOMAIN` (make sure to add the `http://` protocol and the port) and check the **Trigger** to **Push events** , you can filter it for example to only trigger on the `main` branch. If you are using `http`, you should disable SSL verification. Save this webhook to activate.
To test this webhook, you can click **Test > Push events** next to the name. GitLab should show a message that **Hook executed successfully: HTTP 200**, and you can find a `POST /` request in the `gw` logs, assuming debug logging was enabled:
```sh
$ gw /path/to/repo -v --http 0.0.0.0:10101
# ...
2024-03-10T17:58:28.919Z [DEBUG] Received request on POST /
2024-03-10T17:58:29.052Z [DEBUG] There are no updates.
```