Webhooks

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 to trigger deployments directly from your CI/CD pipeline.

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:

{
	// 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/<app-id>?token=<secret>

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.