Triggering Deployments Via Deploy Hooks

A deploy hook is a secret URL that queues a new deployment when something sends it an HTTP POST. There is no authentication header: the secrecy of the URL is the authentication. Use hooks to let a headless CMS, a cron job, a CI pipeline or any other webhook rebuild your project without a git push.

Where To Find Deploy Hooks

Hooks have their own tab: open your project in Orbit and click Hooks, at /orbit/<project-id>/hooks.

The same Deploy hooks panel also appears part way down the project's Settings tab, so you can manage them from either place.

Deploy hooks panel in Orbit

Creating a Deploy Hook

Open Orbit, then your project, then Hooks.
Click Add deploy hook.
Enter a Hook name that will still make sense in six months. The placeholder suggests the shape: "Contentful publish", "Nightly cron".
Choose a Target environment. It defaults to Production (default). If your project has a staging environment, you can point the hook at staging instead.
Click Create hook.

The hook appears in the list with its URL, a Copy URL button and a Delete hook button.

The Hook URL

Hook URLs look like this:

https://kpanel.kapsulehost.com/api/orbit/hooks/<token>

The token is a unique secret generated when you create the hook.

Treat a hook URL exactly like an API key. Anyone who has it can trigger a deployment of your project, and none of Orbit's deploy gates will stop them: deploy locks, required approval, CI required checks and required staging success all apply to push-triggered deploys only, and a hook passes straight through. Never paste a hook URL into a public repository, a shared document, a screenshot or a support ticket.

Triggering a Hook

Send a POST request. No body and no headers are required.

curl -X POST \
  https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Orbit responds with HTTP 202 and the deployment ID. The deployment appears on the Deployments tab within a few seconds.

The endpoint accepts POST only. A GET request will not trigger a deployment. Some older webhook integrations default to GET, so check the method if a hook you have configured never fires.

What a Hook Actually Deploys

The hook resolves its target environment (the one you chose, or the project's production environment), reads that environment's branch, and asks your git provider for the current head commit of that branch. It then queues a deployment of that commit.

That has three consequences worth knowing:

A hook always deploys the branch head. You cannot pass a commit SHA or a branch name in the request body; the request body is ignored entirely.
A hook needs a working provider connection. If you have disconnected GitHub, GitLab or Bitbucket, the hook cannot read the branch head and fails with an error rather than deploying stale code.
A hook re-runs the full build. It is not a rollback and not a promotion; it is a fresh build of whatever is currently on the branch.

Repeated and Overlapping Calls

Orbit handles bursts of hook calls sensibly rather than queuing a build for each one.

If a deployment for the same commit is already in flight on that environment, the hook returns the existing deployment and marks the response as deduplicated. No second build starts.
If a build is running for a different commit on that environment, it is cancelled automatically and replaced by the new one, so you do not pay for a build whose output is already superseded.

This makes hooks safe for a CMS that fires a webhook per published entry. Publishing six pages in a minute produces one build, not six, and does not burn six builds' worth of minutes.

Connecting a Headless CMS

Most headless CMSes have a "webhook on publish" feature. The pattern is always the same: point the webhook at your hook URL, use POST, and leave the authentication settings empty.

Contentful

Go to Settings, then Webhooks, then Add webhook.
Set the URL to your Orbit hook URL.
Set the method to POST.
Set the trigger to Publish, or whichever content events should rebuild the site.
Save.

Sanity

In your project dashboard, go to API, then Webhooks, then Create webhook. Set the URL to your hook URL, the method to POST, and choose the dataset and trigger events.

Prismic

In the dashboard, go to Settings, then Webhooks, and add your hook URL. Prismic calls it on every document publish.

Connecting a Cron Job or CI Pipeline

Any scheduler that can make an HTTP request will do:

# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

For CI, a deploy hook is the simplest option when you want your pipeline to decide whether a deploy happens. It is the recommended approach for Bitbucket Pipelines, since Orbit's CI required checks setting gates on GitHub Actions job names or a GitLab pipeline, not on Bitbucket.

If you need more than "deploy the branch head", use an API token instead of a hook. Orbit, then Tokens, creates scoped bearer tokens for CI/CD with a documented REST API and a ready-made GitHub Actions workflow. API access is included on the Apex plan.

Rebuilding On a Schedule Without a Hook

If all you want is a periodic rebuild, you do not need a hook at all. Scheduled rebuild in Settings, under Runtime, rebuilds production automatically every hour, 6 hours, 12 hours, daily, every 2 days or weekly. It is built for exactly the CMS-driven-site case and there is no secret URL to protect.

Checking Hook Activity

Each hook row shows how many times it has been used and when it was last used, in the form "Used 14 times, last 3 Jul". This is the quickest way to confirm your CMS is actually calling the hook when you think it is.

If the count is not going up, the problem is on the calling side: check the method is POST, the URL is exact, and the integration is not silently failing on a TLS or firewall error.

Deleting a Hook

Click Delete hook on the row and confirm. The dialogue warns that any service using it will stop working, which is exactly what happens.

There is no way to rotate a hook's token in place. If a URL leaks, you delete the hook and create a new one, then update every system that used the old URL. Deletion takes effect immediately, so plan the swap before you delete rather than after.

Troubleshooting

Nothing happens when I call the hook. Check the method is POST. Check the URL character for character, including the token. Check the hook's usage count on the Hooks tab: if it is not incrementing, the request never arrived.

The hook returns an error about the latest commit. Orbit could not read the branch head from your git provider. Reconnect the provider from Orbit, then New project, then Reconnect, and confirm the repository is still accessible.

The hook returns an error about the target environment. The environment the hook pointed at no longer exists, most likely because a staging environment was deleted. Delete the hook and create a new one against a live environment.

The hook fires but the deploy is the same as last time. That is the deduplication behaviour: the branch head has not changed, so there is nothing new to build. Push a commit, or use Deploy now if you specifically want to rebuild the same commit.