Docs

Deploy hooks

A deploy hook is a unique URL that triggers a fresh deployment of one environment when you send it an HTTP POST request. It's the way to redeploy without pushing a commit — useful for external content sources, headless CMS webhooks, or scheduled rebuilds.

When to use a deploy hook

  • External content — your site pulls content from a separate repository or CMS at build time. A change there doesn't push to your project's repo, so nothing redeploys on its own. Point the content source's webhook at a deploy hook to rebuild on every content change.
  • Scheduled rebuilds — a cron job or scheduled GitHub Action that curls the hook on a timer.
  • Custom pipelines — any external system that should kick off a deployment.

Creating a deploy hook

  1. Open the environment and go to its Settings tab.
  2. Under Deploy hooks, select Create deploy hook.
  3. Give it a name you'll recognize later (e.g. "docs content rebuild") and confirm.
  4. Copy the URL immediately — it's shown only once. The URL contains a secret token and cannot be retrieved again. If you lose it, revoke the hook and create a new one.

Creating and revoking deploy hooks requires the Owner or Admin role in the organization.

Triggering a deployment

Send a POST request to the hook URL:

curl -X POST "https://dashboard.velumi.com/api/deploy-hooks/<your-hook-url>"

The response tells you what happened:

  • 200 — a deployment started.
  • 202 — a deployment was queued behind one that's already running. It deploys automatically when the current one finishes.

Both responses include the new deploymentId so you can correlate it in the dashboard.

How it behaves

  • The deployment is identical to a manual deploy or a push — it builds from the environment's current source.
  • If a deployment is already running, the new trigger is queued, not rejected — you won't lose a request by firing the hook during a build.
  • If the environment is stopped, the hook is rejected (409). Start the environment first.

Revoking a deploy hook

In the environment's Settings tab, select Revoke next to the hook. The URL stops working immediately. Other hooks on the environment are unaffected.

Revoke a hook if its URL may have leaked, or when the external system using it is decommissioned.

Security

  • The hook URL is the credential — treat it like a password. Anyone with the URL can trigger a deployment of that environment (and nothing else — it can't read or change your code, variables, or settings).
  • The secret is shown once at creation and never stored in a way we can show you again.
  • Store the URL in your CI/CD secrets (e.g. GitHub Actions secrets), not in plain text in a repository.

Limitations

  • A deploy hook triggers exactly one environment — the one it was created on. Create separate hooks for separate environments.
  • A hook always deploys from the environment's current source. It can't deploy a specific commit or branch other than what the environment already tracks.