Deploy triggers

Warm automatically after every release, from Vercel, Netlify, Shopify, or any CI pipeline.

9 min read

Deploys are the single most reliable way to make an entire site cold at once. A release invalidates caches wholesale, and every visitor in the following minutes pays the rebuild cost simultaneously — exactly when you are most likely to be watching for problems.

Deploy triggers make warming part of shipping. When your deploy succeeds, your platform calls Cache Rocket, and warming starts without anyone opening a dashboard.

Webhook URLs and examples are on Account → Deploy integrations.

How it works

You give your hosting platform or CI a URL to call after a successful deploy. The request carries your API keys as headers, plus a small JSON body saying what to warm.

The general shape

bash

curl -X POST https://api.cacherocket.com/web/v1/public/webhooks/vercel \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -d '{"hostname":"www.example.com"}'

Platform	Webhook path
Vercel	`/web/v1/public/webhooks/vercel`
Netlify	`/web/v1/public/webhooks/netlify`
Shopify	`/web/v1/public/webhooks/shopify`

Note

The exact base URL for your account is shown on the Deploy integrations page, along with a ready-to-copy curl example per platform.

Choosing a payload

The JSON body decides what gets warmed. Three options, from broadest to most surgical:

Body	Effect	Use when
`{"hostname":"www.example.com"}`	Starts every warmer matching that hostname	A normal full release. The usual choice.
`{"crawlerId":"…"}`	Starts one specific warmer	You have several warmers per site and only one is relevant to this deploy.
`{"urls":["https://…"]}`	Priority-warms exactly those URLs	A partial publish, or a handful of pages you know changed.

Priority-warm specific URLs after a partial publish

bash

curl -X POST https://api.cacherocket.com/web/v1/public/webhooks/netlify \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -d '{"urls":["https://www.example.com/","https://www.example.com/pricing"]}'

Vercel

Add the Cache Rocket URL as a Deploy Hook or integration webhook in your project settings, firing on successful production deploys. Authenticate with the X-Public-Key and X-Secret-Key headers.

Next.js apps

If you use @cacherocket/next, you can also expose onVercelDeploy() at /api/cacherocket/deploy and point the Deploy Hook at your own app instead of the public webhook URL.

Tip

Fire on production deploys only. Preview deployments have their own URLs, are not on your verified hostname, and warming them wastes your budget.

Netlify

Use a notification webhook on the deploy succeeded event, pointing at the Netlify path with the same API key headers.

Shopify

Point theme publish or app webhooks at the Shopify path, so storefront changes are rewarmed as soon as they go live.

Any CI pipeline

There is nothing platform-specific about the request — it is an HTTP POST. Add it as the last step of any pipeline.

GitHub Actions

yaml

- name: Warm Cache Rocket after deploy
  run: |
    curl -X POST https://api.cacherocket.com/web/v1/public/webhooks/vercel \
      -H "Content-Type: application/json" \
      -H "X-Public-Key: ${{ secrets.CACHEROCKET_PUBLIC_KEY }}" \
      -H "X-Secret-Key: ${{ secrets.CACHEROCKET_SECRET_KEY }}" \
      -d '{"hostname":"www.example.com"}'

Never hard-code the secret key in a pipeline file

Use your CI provider's encrypted secrets store, as above. Pipeline definitions live in your repository, and a committed secret is a leaked secret.

Alternative: triggerWarm

There is also a simpler endpoint that takes the keys in the body rather than headers, which suits environments where setting custom headers is awkward:

bash

curl -X POST https://cacherocket.com/api/wordpress/triggerWarm \
  -H 'Content-Type: application/json' \
  -d '{"publicKey":"YOUR_KEY","secretKey":"YOUR_SECRET","hostname":"example.com"}'

A companion warmUrls endpoint priority-warms an explicit list of URLs.

Getting the ordering right

Sequence matters more than people expect:

1
Deploy completes and the new version is live
Warming a release that has not finished rolling out just caches the old one.
2
Purge the CDN, if the deploy changed cached output
Otherwise warming re-reads what is already cached and nothing improves.
3
Then trigger warming
Now the warm run fetches genuinely new content and fills the cache with it.

Warming too early is the classic mistake

If the trigger fires before the deploy is fully live, or before the CDN is purged, you will carefully warm the previous version. Hook into the *succeeded* event, not the *started* one.

Common problems

The webhook returns 401.: Keys are wrong, expired, or superseded by a newer pair. Check both header names are exactly X-Public-Key and X-Secret-Key, and look for truncated values in your secrets store.
It returns success but nothing warms.: The hostname in the body probably does not match any active warmer. Confirm the exact hostname, including www, and that the matching warmer is Active.
Warming ran but visitors still hit cold pages.: Almost always ordering — either it fired before the deploy was live, or the CDN was purged after warming rather than before. Add a purge step ahead of the trigger.
Preview deploys are consuming my URL budget.: Restrict the webhook to production deploys only.
Is this the same as a CDN purge?: No. Deploy triggers start warming; they do not invalidate anything. CDN integrations purge and then rewarm. Many teams use both.