Cache purge tokens: purge cached pages from CI, deploy scripts and webhooks

A cache purge token lets your own tools tell Hostney which cached pages are out of date. A deploy pipeline can purge the pages it just changed, a headless CMS can purge a post the moment it is published, and a static site generator can purge the sections it rebuilt. The request goes to your website’s own address and carries the token in a header. No password, no panel session and no Hostney account details are involved.

WordPress sites on Hostney usually do not need one. The Hostney Cache plugin already purges the right pages whenever a post, a page, a menu or a comment changes. Purge tokens are for everything that happens outside WordPress: a headless front end that renders WordPress content, a Node.js, Python or Ruby app with page caching on, or a build that changes files the cache already holds.

What a token can and cannot do#

A token belongs to one website. It can:

• purge up to 50 specific URLs of that website in one request
• purge every cached page under a path, such as /blog/ or /shop/sale/

It cannot clear the whole cache in one request. That is deliberate: a token lives in a CI system, a webhook configuration or an environment variable, and a token that leaks from one of those should not be able to empty your entire cache at once. When you do want everything gone, use Flush cache on the website’s row in the panel.

A token also cannot do anything else. It does not sign in, it cannot read your settings, and it only works on the website it was created for. A token made for www.example.com is refused by shop.example.com .

Create a token#

1. In the control panel, open Nginx caching for the domain.
2. Find the website, open its Manage menu and choose Purge tokens.
3. Click Create token, give it a name that says what will use it (for example “GitHub Actions” or “CMS publish webhook”) and create it.
4. Copy the token from the dialog that opens. It is shown once. Hostney keeps only a fingerprint of it, so nobody can show it to you again, support included.
5. Store it where your tool keeps secrets: a repository secret, your CI system’s encrypted variables, or the webhook settings of your CMS. Never commit it to your code.

A new token starts working within a minute. Each website can have up to 10 tokens, so give every tool its own. The list shows when each one was last used, which tells you whether a token is still needed, and lets you revoke one tool’s access without touching the others.

If you work on a client’s account as a team member, you can create tokens there too, as long as your access includes caching. The tokens you create are removed automatically if your access is revoked or changed.

Send a purge request#

Send a POST request to your website’s own address, at the path /.well-known/hostney-purge , with the token in an Authorization header and a JSON body. With curl, purging two pages looks like this:

curl -X POST https://www.example.com/.well-known/hostney-purge \
  -H "Authorization: Bearer $HOSTNEY_PURGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "purge_urls", "urls": ["https://www.example.com/blog/my-post/", "https://www.example.com/blog/"]}'

Each URL must be a full URL on the same address the request is sent to. Up to 50 fit in one request.

To purge everything under a path, use purge_prefix :

curl -X POST https://www.example.com/.well-known/hostney-purge \
  -H "Authorization: Bearer $HOSTNEY_PURGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "purge_prefix", "prefix": "/blog/"}'

The prefix is a path that starts with / and is more than / on its own. Prefix matching is broad: /blog/ also matches an address such as /en/blog/ . When you need exactly one page, list its full URL instead.

Use the address your website is served on. If your site lives on www.example.com and the bare domain redirects there, send the request to www.example.com : an address that redirects answers with the redirect, not a purge.

Password protection on the website does not get in the way. The token is the credential for this path, so a protected site needs no site password here.

Read the answer#

A successful URL purge answers 200 with what happened to each URL:

{
  "success": true,
  "action": "purge_urls",
  "results": [
    { "url": "https://www.example.com/blog/my-post/", "purged": true },
    { "url": "https://www.example.com/blog/", "purged": false }
  ],
  "total_purged": 1,
  "message": "Purged 1 of 2 URL(s)"
}

"purged": false usually means the page was not in the cache, which is fine: the next visitor gets a fresh copy either way. A cache miss on that request is expected, and the page is cached again from then on.

A prefix purge answers with a count:

{
  "success": true,
  "action": "purge_prefix",
  "prefix": "/blog/",
  "purged_count": 12,
  "message": "Purged 12 item(s) matching prefix"
}

Every refusal is JSON with "success": false and a message that says why:

The limit of 30 requests a minute is a safety net for a pipeline stuck in a loop, not a quota you should plan around. One request can carry 50 URLs, and a prefix covers a whole section.

Examples#

GitHub Actions#

Store the token as a repository secret named HOSTNEY_PURGE_TOKEN , then add a step after your deploy:

      - name: Purge the cached blog pages
        env:
          HOSTNEY_PURGE_TOKEN: ${{ secrets.HOSTNEY_PURGE_TOKEN }}
        run: |
          curl --fail-with-body -sS -X POST https://www.example.com/.well-known/hostney-purge \
            -H "Authorization: Bearer $HOSTNEY_PURGE_TOKEN" \
            -H "Content-Type: application/json" \
            -d '{"action": "purge_prefix", "prefix": "/blog/"}'

--fail-with-body makes the step fail on a refusal while still printing the message, so a revoked token shows up as a failed job instead of a silently stale site.

A publish webhook#

A headless CMS or your own backend can purge the page it just changed. In Node.js:

await fetch('https://www.example.com/.well-known/hostney-purge', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HOSTNEY_PURGE_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'purge_urls',
    urls: [`https://www.example.com/blog/${slug}/`, 'https://www.example.com/blog/'],
  }),
});

Purge the page itself and the listing pages that show it, such as the blog index or a category page. Those are the pages visitors would otherwise see in their old form. For the other places a stale page can hide, how to clear the WordPress cache goes through every layer, from the browser to the CDN.

Keep tokens safe#

• One token per tool. Revoking the CI token then never breaks the CMS webhook.
• Keep tokens in secret stores, not in code, build logs or chat messages. Ellie, the Hostney assistant, can tell you which tokens a website has and when each was last used, but she never sees a token’s value and cannot create one for you.
• If a token may have leaked, revoke it on the website’s Purge tokens list and create a new one. A revoked token stops working within a minute.
• Check Last used from time to time. A token that has not been used in months probably belongs to a tool you no longer run.