Telling me you shipped

Why bother

A deploy is when things break. If I only look once a day, I find out hours later — and by then you have moved on to something else and the change that did it is no longer fresh in your head. When I know you shipped, I run the project's checks against the new version, and if something broke you hear about it while you still remember what you touched.

You do not have to set any of this up. Without a signal I keep checking on the usual schedule.

How the allowance works

A detected deploy can start the project's eligible checks, one run per check, within the shared daily allowance for your whole account. The allowance resets at midnight UTC. Trial allows 20 deploy-triggered check runs per day; Small allows 20, Growing allows 20, and Portfolio allows 100.

The set is all or nothing. If five checks are eligible and only three runs remain, I start none of those five and keep the usual daily checks on their normal schedule. A webhook does not bypass the allowance, and two deploy notifications less than 5 minutes apart are one deploy to me. Asset polling also cannot promise to notice every deploy between looks.

1. Nothing at all, usually

This is the default and for most projects it already works, with nothing for you to choose. I look for two things and take whichever answers. First /.well-known/stillworks, described below; if you serve one, that is the version I go by. Otherwise I compare the addresses of the assets your homepage loads — almost every build tool puts a content hash in those file names, so when they change, you shipped. Editing the words on the page does not count as a deploy.

How often I look depends on which of the two is answering, and the reason is your servers rather than mine. The well-known endpoint is a few hundred bytes, so I read it every 30 minutes and notice a deploy about that fast. Reading your homepage means downloading the whole page, so I do that four times a day — often enough to catch the day's work, rarely enough that I am not knocking on your host all day to watch for something that happens twice a week. Adding the endpoint is what buys the faster look.

If your project's screen says I can tell when you deploy this one, you are done — there is nothing to add.

2. An endpoint that states the version

The more exact half of the same setting, and the one to add when your assets have no fingerprint in them — a server-rendered page with static file names, say. You do not switch anything on for it: serve this at /.well-known/stillworks, with Cache-Control: no-store, and I start reading it on my own the next time I look.

{
  "version": "2026-01-30T09:12:00Z",
  "ownership": "stillworks-verification=<your project id>"
}

The version is any string that changes when you ship. A timestamp you bump by hand is enough — no build step has to produce it — and if you build with an assistant, a line in your CLAUDE.md telling it to update this file with every change keeps it current. Write the value into the source rather than generating it when the endpoint is called: something that changes on every read looks like a deploy every time.

Both values are yours to supply, and the ownership line is what proves the endpoint belongs to the project rather than to somebody who guessed the URL. Your project's screen carries a ready prompt with the real identifier already in it — take it from there rather than filling in the placeholder by hand.

3. A call from your pipeline

The direct webhook is the most exact of them, the fastest, and the one to choose when the deploy finishes somewhere I cannot see. Switch the project to the deploy notification mode and it gets its own URL, with its own token in it. Anyone who has that URL can tell me this project deployed, so keep it in your secrets and out of your logs.

curl -X POST "$STILLWORKS_DEPLOY_URL" \
  -H "Content-Type: application/json" \
  -d '{"version":"'"$(git rev-parse HEAD)"'"}'

version

Optional. A commit sha or build id, up to 200 characters. It is what makes the deploy legible later, when you are looking at which one broke it.

waitMinutes

Optional. How many minutes to let the deploy settle before I start the checks — 0, 1, 2, 5, 10 or 15, and nothing in between. Leave it out and I start straight away. Anything else comes back as a 400 that names the values I take.

202

What a successful call answers: the id of the deploy I recorded, the wait I am honouring, and the moment I will start the checks. The whole request must be JSON and under a kilobyte.

Send it once, as the last step of a deploy that actually succeeded. Telling me about a deploy that failed halfway would have me looking at a version nobody shipped.

Two numbers on this endpoint are counted in minutes and they are not the same rule. The wait is yours and it is about the checks: I have accepted the call, and I hold the runs back for as long as you asked before I start them. The other one is mine and it is about the call: if a second call arrives less than 5 minutes after the one I recorded, I answer it with a 429 and keep the deploy I already have — whatever either call asked me to wait. Two pushes in a row are normal, so treat that answer as nothing to fix and do not let it fail your pipeline.

Let an assistant wire it up

Paste this into Claude Code, Codex, Cursor or whichever assistant you build with, in the repository whose pipeline should send the call.

This project deploys through the pipeline in this repository. After a
successful production deploy, tell stillworks.watch that a new version is
live so it looks at the change straight away.

Do it like this:

1. Read the deploy URL from the STILLWORKS_DEPLOY_URL environment variable
   or secret. It already contains its own token, so it must be stored as a
   secret and never printed in a log.
2. As the last step of the production deploy job — only when every earlier
   step succeeded — send:
   POST $STILLWORKS_DEPLOY_URL
   Content-Type: application/json
   {"version": "<the commit sha or build id that was just deployed>"}
   The body is optional but useful; keep it under a kilobyte.
   If this application needs a moment to settle after a deploy — a cache
   or a CDN warming up — add "waitMinutes" to the same body. It
   takes 0, 1, 2, 5, 10 or 15 and nothing else, and it only delays
   the checks; it does not delay this call.
3. A successful call answers 202. Treat any other answer as a warning, not
   as a failed deploy: the deploy already worked, and failing the job over
   a notification would be worse than the notification being missed.
4. Do not add a retry loop and do not call it more than once per deploy.

Then show me where to put the secret and confirm nothing echoes the URL.

What happens then

I run the project's checks against the version you just shipped. If something is broken you are told the usual way — which still means two failures, never one. You can also ask for a short message confirming a deploy went out clean; that is a checkbox on the project.