Docs

Automatic Cache Clearing with Heroku App Webhooks

Purpose

When you deploy a new release of your Heroku application, cached copies of your pages and assets on our Edge Network can briefly serve stale content. A Heroku App Webhook fixes this by clearing your cache automatically on every release.

Step 1: Copy Your Cache Clearing URL

Your service has a unique cache-clearing webhook URL. You can find it in two places in your dashboard:

  • The “Site Acceleration System” panel on the Home/Status page
  • The Cache Rules > Cache Clearing Webhook page, which also shows these setup instructions

Copy that URL before continuing.

Step 2: Create the Webhook with the Heroku CLI

The fastest way to create the webhook is the Heroku CLI:

heroku webhooks:add \
  --include api:release \
  --level notify \
  --url "PASTE_YOUR_CACHE_CLEARING_URL_HERE" \
  --app your-app-name

The api:release event fires on every successful release: code deploys, config var changes, and rollbacks all count.

To confirm it was created:

heroku webhooks --app your-app-name

Alternative: Create the Webhook in the Heroku Dashboard

If you prefer the browser:

  1. Open your app in the Heroku Dashboard
  2. Open the More menu (top right of your app’s page) and choose View webhooks
  3. Click Create Webhook
  4. Paste your cache-clearing URL into the Payload URL field
  5. Select api:release under Event Types
  6. Click Add Webhook

Heroku updates their dashboard layout from time to time. If the menus have moved, the CLI method above always works, and Heroku’s own App Webhooks documentation reflects the current UI.

Step 3: Verify It Works

Deploy any change to your application (an empty commit is fine):

git commit --allow-empty -m "Test cache clearing webhook"
git push heroku main

Then check the Audit Log or the cache status on your dashboard’s Home page. You should see a cache clear recorded shortly after the release finishes.

A Note on Heroku Deploy Hooks

App Webhooks replaced the retired “Heroku Deploy Hooks” add-on. If you set up cache clearing with Deploy Hooks in the past, it stopped firing when that add-on was sunset, and you should recreate it using the steps above.