The application listens for incoming webhooks on the /v1/webhook endpoint with the port specified by the HTTP_PORT environment variable, see App Settings. The webhook payload is expected to be in JSON format and must contain the payload from a supported the Git provider, see Supported Git Providers.

With custom Target

You can specify multiple deployment target configurations in a mono-repo style setup using the application's dynamic webhook path. This allows you to deploy to different targets/locations from a single repository.

If a webhook payload gets sent to a custom path suffix /v1/webhook/<custom_name>, the application will look for a deployment configuration file with the same pattern in its name .doco-cd.<custom_name>.yaml.

Examples

Webhook Target	Deployment Config File
`/v1/webhook`	`.doco-cd.yaml`
`/v1/webhook/gitea`	`.doco-cd.gitea.yaml`
`/v1/webhook/paperless-ngx`	`.doco-cd.paperless-ngx.yaml`
`/v1/webhook/my.server.com`	`.doco-cd.my.server.com.yaml`

Query Parameters

`wait`

Webhooks trigger deployments asynchronously by default, meaning the application will respond immediately to the webhook request and process the deployment in the background. Use the wait=true query parameter to make the application wait for the deployment to finish before responding. This may increase response time, and some Git/SCM providers might time out the request if the deployment takes too long. Even if the request times out, the deployment will still continue.

Example: /v1/webhook?wait=true

REST API

The application exposes a RESTful API at the /v1/api endpoint.

Authentication

Set the API_SECRET or API_SECRET_FILE environment variable in the container to enable the API, see App Settings.

Use the x-api-key header to authenticate requests to the API using the secret value.

Example:

curl -H "x-api-key: your_api_key" http://example.com/v1/api/projects

Endpoints

Polling

Endpoint	Method	Description	Query Parameters
`/v1/api/poll/run`	POST	Trigger a poll run for all polling targets in the body (JSON).	- `wait` (boolean, default: `true`): Wait for the poll run to finish before responding.

The request body must be a JSON array of poll configurations, each containing at least a url field containing the Git clone URL to the repository.

The fields run_once and interval will be ignored for poll runs triggered via the API, as they are only relevant for the scheduled poll runs.

Example Request

Minimal example using the default settings:

curl --request POST \
  --url 'https://cd.example.com/v1/api/poll/run?wait=true' \
  --header 'content-type: application/json' \
  --header 'x-api-key: your-api-key' \
  --data '[
  {
    "url": "https://github.com/your/repo.git",
  }
]'

Example with custom reference and inline deployment configuration:

curl --request POST \
  --url 'https://cd.example.com/v1/api/poll/run?wait=true' \
  --header 'content-type: application/json' \
  --header 'x-api-key: your-api-key' \
  --data '[
  {
    "url": "https://github.com/your/repo.git",
    "reference": "dev",
    "deployments": [
      {
        "name": "my-app",
        "working_dir": "/app",
        "env_files": [
          ".env"
        ]
      }
    ]
  }
]'

Compose Projects

Endpoint	Method	Description	Query Parameters
`/v1/api/projects`	GET	List all deployed compose projects	- `all` (boolean, default: `false`): Return all projects including inactive ones.
`/v1/api/project/{projectName}`	GET	Get details of a project
`/v1/api/project/{projectName}`	DELETE	Remove a project	- `volumes` (boolean, default: `true`): remove all associated volumes. - `images` (boolean, default: `true`): remove all associated images.
`/v1/api/project/{projectName}/start`	POST	Start a project
`/v1/api/project/{projectName}/stop`	POST	Stop a project
`/v1/api/project/{projectName}/restart`	POST	Restart a project

Swarm Stacks

Endpoint	Method	Description	Query Parameters
`/v1/api/stacks`	GET	List all deployed Swarm stacks
`/v1/api/stack/{stackName}`	GET	Get details of a Swarm stack
`/v1/api/stack/{stackName}`	DELETE	Remove a Swarm stack
`/v1/api/stack/{stackName}/scale`	POST	Rescale a Swarm stack or service	- `replicas` (integer): Scale to n replicas. - `service` (string, optional): Name of service to scale. - `wait` (boolean, default: `true`): Wait for service to be running/healthy
`/v1/api/stack/{stackName}/restart`	POST	Restart/Redeploy a Swarm stack or service	- `service` (string, optional): Name of service to restart.
`/v1/api/stack/{stackName}/run`	POST	Trigger one or all jobs in stack	- `service` (string, optional): Name of the job service to run.

Global Query Parameters

Query Parameter	Type	Description
`timeout`	integer	Timeout in seconds (default: `30`).

Example Request

List all deployed compose projects

curl -H "x-api-key: your_api_key" "http://example.com/v1/api/projects?all=true"

Remove a specific project without removing associated volumes

curl -X DELETE -H "x-api-key: your_api_key" "http://example.com/v1/api/project/my_project?volumes=false"

Restart a specific project with a custom timeout

curl -X POST -H "x-api-key: your_api_key" "http://example.com/v1/api/project/my_project/restart?timeout=60"

Health Check

The application exposes a health check endpoint at /v1/health that, if the application is healthy, returns a 200 status code and the following JSON response:

{
  "details": "healthy"
}

If the application is not healthy, the endpoint returns a 503 status code and the following JSON response:

{
  "details": "unhealthy",
  "error": "some error message"
}

Prometheus Metrics

The application exposes Prometheus metrics at the /metrics endpoint. This endpoint provides various metrics about the application's performance and health, which can be scraped by a Prometheus server for monitoring purposes.

By default, this endpoint is available on Port 9120, but can be configured using the METRICS_PORT environment variable, see App Settings.

Grafana Dashboard

An example for a Grafana Dashboard can be found at Grafana Dashboard #583.