From 58dc3f271f30be3f641a768e9c22de20c30ba39c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timo=20K=C3=B6ssler?= Date: Tue, 21 Jul 2026 11:22:03 +0200 Subject: [PATCH] docs: Create webhooks docs --- .../advanced/architecture/repositories.mdx | 17 ---- .../{architecture => }/notifications.mdx | 0 content/docs/configuration/webhooks.mdx | 82 +++++++++++++++++++ 3 files changed, 82 insertions(+), 17 deletions(-) rename content/docs/advanced/{architecture => }/notifications.mdx (100%) create mode 100644 content/docs/configuration/webhooks.mdx diff --git a/content/docs/advanced/architecture/repositories.mdx b/content/docs/advanced/architecture/repositories.mdx index d5bd777..2fbdc6c 100644 --- a/content/docs/advanced/architecture/repositories.mdx +++ b/content/docs/advanced/architecture/repositories.mdx @@ -54,23 +54,6 @@ Use polling when: OrcaCD listens for push events from your Git provider via webhook. This is more efficient than polling and reacts to new commits instantly. -#### Setting Up a Webhook - -1. Add the repository with sync type **Webhook**. -2. After saving, open the repository settings. A webhook URL and secret should be generated. -3. Register this webhook in your Git provider: - - **GitHub:** Settings → Webhooks → Add webhook - - Payload URL: `https://your-hub-url/api/v1/webhooks/repositories/` - - Content type: `application/json` - - Secret: copy from OrcaCD - - Events: **Just the push event** - - **GitLab:** Settings → Webhooks - - URL: `https://your-hub-url/api/v1/webhooks/repositories/` - - Secret token: copy from OrcaCD - - Trigger: **Push events** - ### Manual The repository is only synced when you explicitly trigger a sync from the UI or API. diff --git a/content/docs/advanced/architecture/notifications.mdx b/content/docs/advanced/notifications.mdx similarity index 100% rename from content/docs/advanced/architecture/notifications.mdx rename to content/docs/advanced/notifications.mdx diff --git a/content/docs/configuration/webhooks.mdx b/content/docs/configuration/webhooks.mdx new file mode 100644 index 0000000..237bade --- /dev/null +++ b/content/docs/configuration/webhooks.mdx @@ -0,0 +1,82 @@ +--- +title: Webhooks +description: Configure webhooks to trigger deployments in OrcaCD +--- + +While OrcaCD supports polling for changes in your Git repository or container registry, webhooks are a more efficient way to trigger deployments. +Webhooks allow OrcaCD to receive notifications from your Git provider or container registry when changes occur, enabling faster and more responsive deployments. +Another alternative is to use the [OrcaCD GitHub Action](../guides/github-actions) to trigger deployments directly from your CI/CD pipeline. + + + This doc is about incoming webhooks that trigger deployments in OrcaCD. For outgoing webhooks, see + [Notifications](/docs/advanced/notifications). + + +## Git Providers + +This webhook endpoint triggers a check of the Git repository for changed Compose files and triggers a deployment if changes are detected. + +For setting up webhooks for your Git provider, you need the webhook URL and secret generated by OrcaCD when you add a repository with sync type **Webhook**. +In case you have already added the repository, change the sync type to **Webhook** in the repository settings to generate the webhook URL and secret. + +### GitHub + +Go to the Settings → Webhooks → Add webhook page of your repository. Paste the webhook URL and secret from OrcaCD and configure the webhook as follows: + +- Content type: `application/json` +- Events: **Just the push event.** + +### Gitlab / Gitea + +Go to the Webhooks settings page of your repository. Paste the webhook URL and secret from OrcaCD and make sure to only select the **Push events** trigger. + +### Generic + +You can also easily call the webhook endpoint from any system by sending a POST request to the webhook URL with the secret in the `Authorization` header. +You can optionally include a JSON body with the following fields, but it's not required: + +```json +{ + // Optional body fields + "ref": "refs/heads/main", + "branch": "main", + "commit": "abc123" +} +``` + +## Container Registries + +This endpoint will trigger a image pull and container recreation if the image digest has changed. +This can be used for mutable tags like `latest` or `stable` to ensure that the latest image is always deployed, even without adjusting the tag in the Compose file. + +The webhook URL and secret can be generated in OrcaCD by clicking on Applications -> Your Application -> Image-Polling (Settings). +Click on generate webhook and the secret will be displayed. Copy it and afterwards you will also see the webhook URL. +You can re-generate the secret at any time or disable the webhook if you no longer want to use it. + +### GitHub Packages + +Go to the Settings → Webhooks → Add webhook page of your repository linked to your Package (Container). +This webhooks is only triggered for packages that are linked to the selected repository. Paste the webhook URL and secret from OrcaCD and select the `application/json` content type option. +Then select `Let me select individual events.` and make sure that only the `Registry packages` event is selected. + +### Docker Hub + +Open your repository on Docker Hub and go to the Webhooks tab. Enter any name for the webhook and paste the webhook URL from OrcaCD. +As Docker Hub does not support secrets for webhooks, you can add the secret to the webhook URL as a query parameter like this: + +``` +https://orcacd.example.com/api/v1/webhooks/images/?token= +``` + +Click on **Add webhook** to create the webhook. + +### Harbor + +Select a project in Harbor and go to the Webhooks tab. Click on **New Webhook** and enter any name for the webhook. +Make sure that Notify type is set to `http` and payload format is set to `default`. Only select the `Artifact pushed` event and uncheck all other events. +Paste the webhook URL from OrcaCD and add the secret in the `Auth Header` field. +It's also strongly recommended to enable TLS verification for the webhook. Click on **Add** to create the webhook. + +### Generic + +Send a HTTP POST request to the webhook URL with the secret in the `Authorization` header and without any body.