Setup Webhook

This page shows how to set up a webhook for your deployments.

A webhook is an http request that is sent to a URL when a specific event occurs.

Table of Contents

• Webhook Endpoint
• GitHub
• Gitea
• Gitlab

Webhook Endpoint

Doco-CD listens on the URL path /v1/webhook for incoming webhooks (http requests). The full url would look like this for example: https://your-server.com/v1/webhook I recommend that you use HTTPS so that your secret key is transmitted in encrypted form.

GitHub

1. Go to your repository settings.
2. Click on Webhooks.
3. Click on the Add webhook button.
4. Fill in the following fields:
   • Payload URL: The URL to the app endpoint, e.g. https://example.com/v1/webhook.
   • Content type: Set this to application/json.
   • Secret: The WEBHOOK_SECRET you have set in your app configuration (See App Settings).
   • SSL verification: Enable this if you have a valid SSL certificate for the app endpoint.
   • Which events would you like to trigger this webhook?: Set this to Just the push event or Let me select individual events and then Pushes and/or Branch or tag creation.
   • Active: Enable this to activate the webhook.

Note

GitHub webhooks are limited to 10 seconds for the delivery timeout. If your deployment takes longer than this (e.g., when pulling big images), the webhook will appear as failed in the GitHub UI, but the deployment will still continue. You can check the status of the deployment in the doco-cd logs.

Gitea

1. Go to your repository settings.
2. Click on Webhooks.
3. Click on the Add webhook button and select Gitea in the dropdown.
4. Fill in the following fields:
   • Target URL: The URL to the app endpoint, e.g. https://example.com/v1/webhook.
   • HTTP Method: Set to POST.
   • POST Content Type: Set to application/json.
   • Secret: The WEBHOOK_SECRET you have set in your app configuration (See App Settings).
   • Trigger On: Set this to Push Events or Custom Events... and then Create and/or Push.
   • Branch filter: Set this to the branch you want to trigger the webhook or * for all branches.
   • Active: Enable this to activate the webhook.

Note

You may need to extend the webhook delivery timeout in the Gitea config file app.ini to allow for longer running deployments (e.g., when pulling big images) This can be done by setting the DELIVER_TIMEOUT variable in the [webhook] section of the config file. You may want to increase this to 30 seconds or more depending on your deployment time.

In addition, you may need to set the ALLOWED_HOST_LIST variable in the [webhook] section of the config file to allow the webhook to be delivered to the app endpoint.

Gitlab

1. Go to your repository settings.
2. Click on Webhooks.
3. Click on the Add new webhook button.
4. Fill in the following fields:
   • URL: The URL to the app endpoint, e.g. https://example.com/v1/webhook.
   • Secret Token: The WEBHOOK_SECRET you have set in your app configuration (See App Settings).
   • Trigger: Set this to Push events and/or Tag push events.
   • SSL verification: Enable this if you have a valid SSL certificate for the app endpoint.
5. Click on the Test button and then Push events to test the webhook.

Note

You may need to extend the webhook delivery timeout in the Gitlab config file gitlab.rb to allow for longer running deployments (e.g., when pulling big images) This can be done by setting the webhook_timeout variable in the gitlab.rb file. You may want to increase this to 30 seconds or more depending on your deployment time.