Webhooks & API Deploys

Every project gets two unique, token-authenticated URLs, shown on its Settings page:

• POST /api/webhook/<token>: accepts push webhook payloads from GitHub, Gitea, Forgejo, and GitLab.
• POST /api/deploy/<token>: a plain deploy trigger for CI pipelines and scripts.

Both endpoints are unauthenticated by session (no login required) and instead rely on the token embedded in the URL, which is a 256-bit random value generated per project.

Note

Conveyor downloads release archives from the GitHub API regardless of which webhook triggers the deploy. Pushing to a Gitea, Forgejo, or GitLab instance only works as a trigger if that instance mirrors to (or is otherwise the same commit as) the GitHub repository configured on the project. The project’s Repository field must be a GitHub repo.

Setting up a push webhook

In your git host’s webhook settings, add the project’s webhook URL (.../api/webhook/<token>) as the payload URL, and set the content type to JSON. Configure it to send push events only.

• GitHub / Gitea / Forgejo: set the project’s Webhook Secret (shown on the project Settings page) as the webhook’s secret. Conveyor verifies the HMAC-SHA256 signature GitHub sends as X-Hub-Signature-256, or the bare hex HMAC Gitea/Forgejo send as X-Forgejo-Signature / X-Gitea-Signature.
• GitLab: paste the webhook secret into GitLab’s Secret token field. GitLab doesn’t sign payloads; it echoes the secret back verbatim in the X-Gitlab-Token header, which Conveyor compares directly.

If a project has no webhook secret set, signature/token verification is skipped and the URL’s own token is the only protection. Setting the secret is optional but recommended.

Conveyor detects which provider sent a request from its headers (X-Gitlab-Event, X-Forgejo-Event, X-Gitea-Event, falling back to X-GitHub-Event), and only triggers a deployment for actual push events. Everything else gets a 200 {"status":"ignored"} response, so you can point any event type at the URL without it accidentally deploying.

Branch matching

The webhook only triggers a deployment when the pushed branch matches the project’s configured branch. A push to any other branch returns 200 with {"status":"ignored","reason":"branch mismatch: got <branch>, want <configured>"}. Nothing is deployed, and nothing is treated as an error.

Deploying from CI

For CI pipelines or scripts, POST to the deploy endpoint directly:

curl -X POST https://conveyor.example.com/api/deploy/<token>

You can optionally attach commit metadata (shown in the deployment history) with a JSON body:

curl -X POST https://conveyor.example.com/api/deploy/<token> \
  -H "Content-Type: application/json" \
  -d '{"sha": "abc1234", "message": "Release v1.2.0", "author": "ci-bot"}'

This endpoint doesn’t check the branch: it deploys whatever the project is configured to deploy, regardless of what triggered the CI run. It’s meant to be called from a pipeline that already knows it’s building the right branch.

Responses

Both endpoints return 200 with {"status":"deploying","deployment_id":<id>} on success. Other outcomes:

Status	Meaning
403	Blocked by a no-deploy window
409	A deployment is already running for this project
401	Invalid webhook signature (push webhook only)
404	Unknown or invalid token

Notifications

Wire up Discord or Slack notifications to get alerted on deploy start, success, or failure, regardless of whether the deploy was triggered manually, by webhook, or by the API.