Triggering deployments via deploy hooks

A deploy hook is a secret URL that triggers a new deployment when you send an HTTP POST request to it. No authentication header is needed - the secrecy of the URL is the authentication. You use deploy hooks to let external systems - a headless CMS, a cron job, a CI pipeline, or another webhook - trigger a rebuild without a git push.

Where to find deploy hooks

Hooks live on their own tab: Orbit -> [your project] -> Hooks

You can also access them via Orbit -> [your project] -> Settings, where the same Deploy hooks panel appears partway down the page.

Creating a deploy hook

1. Go to Orbit -> [your project] -> Hooks
2. Click New hook
3. Enter a Name to identify the hook - for example "Contentful publish" or "Nightly cron"
4. Choose a Target environment (optional). Defaults to Production. If your project has a staging environment, you can direct the hook at staging instead.
5. Click Create hook

After creating, the hook appears in the list. Click on it to expand the row and see the full URL and a ready-to-use curl example.

The hook URL format

Hook URLs look like this:

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

The token is a unique secret generated when you create the hook. Treat it like an API key. Anyone with the URL can trigger a deployment of your project.

Triggering a hook

Send a POST request to the URL with no body required:

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

That is all. Orbit queues a deploy of the latest commit on the target environment's branch. You will see the deployment appear in the Deployments tab within a few seconds.

Connecting a headless CMS

Contentful

1. In Contentful, go to Settings -> Webhooks -> Add webhook
2. Set the URL to your Orbit hook URL
3. Set method to POST
4. Set the trigger to "Publish" (or whichever content events should trigger a rebuild)
5. Save

Sanity

In your Sanity project dashboard, go to API -> Webhooks -> Create webhook, set the URL to your hook URL, method to POST, and choose the dataset and trigger events.

Prismic

In the Prismic dashboard, go to Settings -> Webhooks, add your hook URL as a new webhook. Prismic calls the URL on every document publish.

Other CMSes

Most headless CMSes have a "webhooks on publish" feature. The pattern is the same: point the CMS webhook at your Orbit hook URL, use POST, and no authentication headers are needed.

Checking hook activity

In the Hooks tab, each hook row shows:

• How many times it has been triggered (shown as "N triggers")
• When it was last used

This is useful for confirming your CMS is actually calling the hook when you expect it to.

Deleting a hook

Expand a hook row by clicking on it, then click Delete hook. Any system that has the URL saved will stop triggering deployments immediately. You will need to create a new hook and update those systems with the new URL.

Security notes

• The token in the URL is the only form of authentication. If a hook URL is leaked, regenerate it by deleting the hook and creating a new one, then updating any systems that used the old URL.
• Hook calls always deploy the latest commit on the branch. They do not accept a specific commit SHA or branch name in the request body.
• There is no rate limiting documented on deploy hook calls beyond Orbit's general deploy queue. Rapid repeated calls queue as separate deploys.