Webhooks

A webhook is just a URL you send a small HTTP request to. When the agent receives that request, it starts a deployment. This is how your git server (or any script) tells the agent “new code is ready — deploy it”.

Every project gets two webhook URLs. You find them on the project’s Deployments tab, in the Webhooks card:

GET|POST /hooks/<slug>/<token>/git
GET|POST /hooks/<slug>/<token>/zip

Both methods work. POST with a JSON body is the usual way (and what git servers send). GET is there for convenience — you can paste the URL into a browser or a curl with no body to trigger a default deploy, and you can pass the same overrides as query parameters (see below). A GET carries no body, so everything comes from the query string or the project’s own configuration.

The <token> is a long random secret built into the URL. To change it, click Rotate token in the same Webhooks card. The old URL stops working immediately.

Important: that secret token is the only thing protecting the webhook. Anyone who has the full URL can trigger a deploy. They can also send their own git_url or zip_url, or upload a ZIP, and deploy any code they like. So treat the URL like an admin password: keep it private and rotate it if it ever leaks.

Git endpoint

Body is optional JSON:

Field Meaning
git_url override the project’s configured repo for this run
branch override the configured branch
commit build an exact commit (fetched on top of the shallow clone); if it can’t be fetched or checked out, the run fails rather than deploying branch HEAD
callback_url send this run’s status reports to this https:// URL instead of the project’s — see Per-run callback URL

Plain GitHub / GitLab / Gitea push payloads are accepted as-is: the commit is read from after/checkout_sha; anything missing falls back to the project’s configuration. Unknown fields are ignored. Point the git server’s webhook at the /git URL with content type application/json (a form-encoded body is rejected with 422).

A git server fires its webhook for more than the deploys you want, so the agent filters what it receives — each check runs only when its signal is present, so a plain curl or script call is never filtered:

A skipped hit still answers 202, with {"skipped": "<reason>"}, and shows on the Audit page. The payload’s repository.* URL is used only when the project has no repo configured — a push to a mirror never redirects which repo the project builds from. When it is used, the HTTPS form (clone_url / git_http_url) is preferred, and an SSH form (git@host:owner/repo.git or ssh://…) is rewritten to https:// — the agent clones over HTTPS only (see Git access).

After first-run setup the agent listens only on 127.0.0.1, so call webhooks through your admin domain (the same nginx site that serves the panel), not the raw :8044 port:

# simplest: deploy the configured repo/branch
curl -X POST https://ci.example.internal/hooks/my-app/<token>/git

# specific branch (POST body)
curl -X POST https://ci.example.internal/hooks/my-app/<token>/git \
  -H 'content-type: application/json' -d '{"branch":"release"}'

# same thing with a plain GET — overrides go in the query string
curl 'https://ci.example.internal/hooks/my-app/<token>/git?branch=release'

For a GET, pass git_url, branch, commit and/or callback_url as query parameters; each falls back to the project’s configuration when omitted. A POST body always wins over a query parameter for the same field.

ZIP endpoint

# POST body
curl -X POST https://ci.example.internal/hooks/my-app/<token>/zip \
  -H 'content-type: application/json' \
  -d '{"zip_url":"http://artifacts.internal/app-1.2.3.zip"}'

# GET with the URL as a query parameter
curl 'https://ci.example.internal/hooks/my-app/<token>/zip?zip_url=http://artifacts.internal/app-1.2.3.zip'

The ZIP endpoint needs a zip_url (from the POST body or the ?zip_url= query parameter) or the ZIP file itself. Without either one it returns 422. It also takes an optional callback_url, in the body or as ?callback_url= (see Per-run callback URL).

Upload the ZIP

You can also send the ZIP file itself in the POST body. The agent then has nothing to download. Set the Content-Type to application/zip (or application/x-zip-compressed, or application/octet-stream):

curl -X POST https://ci.example.internal/hooks/my-app/<token>/zip \
  -H 'content-type: application/zip' \
  --data-binary @app.zip

# Deploy the last commit of a git checkout, without its uncommitted files
git archive --format=zip HEAD | curl -X POST https://ci.example.internal/hooks/my-app/<token>/zip \
  -H 'content-type: application/zip' --data-binary @-

To get status reports for an uploaded ZIP, put the callback URL in the query string, because the body is the ZIP: …/zip?callback_url=https%3A%2F%2Fcd.example.internal%2Frun-status%2F42.

The upload may be at most zip_max_bytes (default 500 MB); a bigger one is refused with 413. If nginx sits in front of the agent, its client_max_body_size for the agent’s domain must allow the upload too. The run shows up like a manual upload (source upload:<file>).

The archive may have the compose file at its root or inside a single top-level directory.

Limits and safety checks:

What this means. The ZIP URL comes from whoever calls the webhook. These checks stop a caller from using the agent to reach services that listen only on the server itself, or to fill the disk.

Responses

Code Meaning
202 accepted; body {"run_id": N} — or {"skipped": "<reason>"} when the event/branch filter (or a deploy pause) dropped it
404 unknown project, bad token, or archived project (all look the same on purpose)
413 request body too large (the webhook body cap is 1 MiB; an uploaded ZIP may be up to zip_max_bytes)
422 body present but unusable (bad JSON, missing zip_url, empty ZIP upload, no git URL anywhere, invalid callback_url); the body says why, and no run is started
500 the agent could not queue the run; see the ci-agent log

run_id is the run’s global id — unique across all projects. It is not the per-project #number shown in the run list (both appear on the run’s page, as Run ID and in the title). Keep run_id if you want status updates: the status callback sends it back with every report.

Status callback

A webhook answers right away with a run_id, but the deploy takes longer. If another system started the deploy (a CD tool, a release script), it usually wants to know how it ended. Instead of polling, give the project a status callback URL: the agent then sends an HTTP POST to that URL every time the run changes status.

What this means. You call the agent to start a deploy; the agent calls you back to say how it is going. The run_id in each report is the same number the webhook returned, so you can match reports to your requests.

Which runs are reported

Only runs that a caller requested and got a run_id for:

These runs are not reported — nobody outside is waiting for them:

There are two ways to say where the reports go:

When a run has its own callback URL, it reports only there. The project’s URL is used for runs that came without one.

Set it up

  1. Open the project and go to the Settings tab.
  2. Below Auto-redeploy every (hours), fill in Status callback URL — for example https://cd.example.internal/ci-agent/status. It must start with http:// or https://.
  3. Optional: fill in Callback token. The agent sends it in the X-CiAgent-Token header, so your receiver can check the request really came from this server.
  4. Click Save callback.

To turn it off, clear the URL and save. The token is stored encrypted and is shown in clear text on the Settings tab, like env values.

screenshot: Settings tab with the Status callback URL and Callback token fields

Per-run callback URL

A system that starts many deploys (a CD tool) often needs each report to go to a URL that names its deploy, for example https://cd.example.internal/run-status/<deploy id>. The project’s single callback URL can’t do that. So send the URL with the webhook call instead:

curl -X POST https://ci.example.internal/hooks/my-app/<token>/zip \
  -H 'content-type: application/json' \
  -d '{"zip_url":"https://artifacts.internal/app-1.2.3.zip",
       "callback_url":"https://cd.example.internal/run-status/42"}'

The run’s page and the API show which URL a run reports to (see below).

What the agent sends

curl -X POST "<your callback URL>" \
  -H "Content-Type: application/json" \
  -H "X-CiAgent-Token: <your token>" \
  -d '{"status": "failed", "run_id": 123, "error": "build failed: …"}'

A successful run sends:

{ "status": "success", "run_id": 123 }
Field Meaning
status the run’s new status (table below)
run_id the run_id the webhook or API returned
error only for failed, interrupted and timeout: why it stopped. Secrets (project and shared env values, git credentials) are replaced with *****; long text is cut at 2000 characters

The header is left out when no token is set.

Statuses, in the order they happen:

Status Kind Meaning
queued in progress the run is waiting its turn
fetching in progress downloading the code (git clone or ZIP)
building in progress building images
testing in progress running the ci-test service (only if the project has one)
deploying in progress starting the new containers and checking health
success final deployed and healthy
failed final something went wrong; see error
timeout final the run hit its time limit
interrupted final the agent restarted while the run was in progress. Sent after the restart; error is ci-agent restarted while the run was in progress
cancelled final someone cancelled it
superseded final a newer webhook deploy replaced it before it ran (see Queue behavior)

A redeploy or recreate skips fetching and building. Each run reports queued first and one final status last (a final status can arrive twice — see Delivery and retries).

Restart while a run is still queued. Some runs have not started yet when the agent restarts. Webhook runs and API deploys from git or a ZIP URL can’t be resumed, because the agent did not save their source. They end as failed with the error lost at restart. Call the webhook (or the API) again to retry. Queued redeploys, recreates and image/inline deploys are put back in the queue and still run.

Delivery and retries

Note. A webhook that answers {"skipped": …} (filtered push, or deploys paused) created no run, so no callback follows. Treat a 202 without run_id as “not deployed”.

Common problems and fixes

Problem Fix
No reports arrive Check that the run was started by a webhook or the API (panel deploys, auto-redeploys and env changes are not reported), and that it was sent a callback_url or the Status callback URL is set on that project
The webhook answers 422 with “callback_url must …” The callback_url is not a valid absolute https:// URL of at most 2000 characters. Fix it and call again; no run was started
The run page says failed (…) The detail shows the HTTP code or connection error. Make sure the agent’s server can reach the URL. A 4xx other than 408/429 is not retried — fix the receiver and redeploy
Saving the URL says the host “is not allowed” Link-local addresses (169.254.*, fe80::), 0.0.0.0, :: and 255.255.255.255 are blocked. Loopback (127.0.0.1) and LAN addresses are allowed
The receiver gets the same final status twice Expected after a retry or an agent restart. Ignore repeats
The webhook answers 404 but the URL is right The project is archived. Unarchive it on the Settings tab
A ZIP deploy fails with “disallowed loopback/link-local address” The zip_url points at this server itself (127.0.0.1, localhost). Use the server’s LAN address or another host

Queue behavior

Webhook runs collapse. When a new webhook run is queued, every older webhook run of the same project that is still waiting in the queue is marked superseded. Only the newest one runs. A run that has already started is not touched.

Runs from the admin panel and the API (deploys, redeploys, recreates) never collapse, and they never replace a webhook run.

What this means. If you push five commits quickly, the agent builds the one that is running now and then only the newest commit. It does not build the three in between.

Paused and archived projects

Paused. On the Settings tab, click Pause deploys to freeze a project. The running stack stays up. Then:

Click Resume deploys to let webhooks through again.

Archived. A webhook call to an archived project answers 404, the same as a wrong token. Click Unarchive on the Settings tab to turn the webhook back on.

See Operations.