Publishing makes a release in Colophon. A website that reads the delivery API on every request sees it at once; a site that is built ahead of time, or sits behind a CDN, needs to be told. Website connections do the telling, after every release, and each release’s receipt records what they did and what they saw. In the API a website connection is a destination.
The three kinds
Section titled “The three kinds”| In the Studio | kind |
After each release, Colophon… | Address |
|---|---|---|---|
| Site rebuild | webhook |
posts an announcement of the release, so your site can rebuild | Webhook URL (https) |
| Cache clear | cdn |
posts the cache tags the release changed, so the CDN in front of your site drops those copies | Purge URL (https) |
| Site check | probe |
reads a page of your live site and looks for the release number in it | URL to check (https) |
The first two send something; only a site check proves anything about what readers get. A receipt can only say a release is verified when a site check saw it.
Connections belong to one environment (production here). Seeing and changing them needs the
destinations.manage permission: owners and developers have it, and so does a full-access API token. Other
roles don’t see them in the Studio at all, since an address can carry a secret.
Add a connection
Section titled “Add a connection”In the Studio
Section titled “In the Studio”- Open the project’s Settings → Website connections and press Add a connection.
- Choose the Kind: Site rebuild, Cache clear or Site check.
- Give it a Connection name you’ll recognise on each receipt, such as
Site buildorEdge cache. - Paste the address. For a site check you may also set a Location; see Where a site check runs.
- Press Add website connection.
Each connection in the list has a checkbox to turn it on or off: Announce releases, Purge on release or Check each release.
With the API
Section titled “With the API”GET /api/v1/projects/{project}/environments/{environment}/destinations the connectionsPOST /api/v1/projects/{project}/environments/{environment}/destinations add onePUT /api/v1/projects/{project}/environments/{environment}/destinations/{destination} turn one on or offGET /api/v1/projects/{project}/environments/{environment}/jobs?generation= delivery jobsGET /api/v1/projects/{project}/environments/{environment}/releases/{generation} a release's receiptThe body of a new connection:
| Member | Required | Rules |
|---|---|---|
kind |
No | webhook (the default), cdn or probe |
name |
Yes | 1 to 100 characters, no control characters |
url |
Yes | https, a public address, no user name or password in it, at most 2,000 characters |
location |
No | Site checks only: 1 to 63 lowercase letters, digits and dashes |
curl -i -X POST "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/destinations" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"kind": "webhook", "name": "Site rebuild", "url": "https://build.example.com/hooks/colophon"}'HTTP/1.1 201 Createdcontent-type: application/jsonx-request-id: 01a1ee89-7894-7169-81e8-c5857e1af4a6content-length: 216date: Wed, 18 Nov 2026 12:02:29 GMT
{ "data": { "id": "01a1ee89-7896-7559-80c7-d436038db473", "kind": "webhook", "name": "Site rebuild", "url": "https://build.example.com/hooks/colophon", "enabled": true, "location": null, "created_at": "2026-11-18T12:02:29.141469Z" }}A new connection is on at once: the next release is announced to it. This route takes no Idempotency-Key,
so sending the same request twice makes two connections.
Pause one
Section titled “Pause one”PUT with {"enabled": false} pauses a connection, and {"enabled": true} turns it back on. The answer is
204 No Content (DESTINATION is the id the create answered):
curl -i -X PUT "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/destinations/$DESTINATION" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"enabled": false}'HTTP/1.1 204 No Contentx-request-id: 01a1ee89-78bf-7187-a333-2476b5c8ef39date: Wed, 18 Nov 2026 12:02:29 GMTA paused connection gets nothing from the releases that follow, and it doesn’t count towards their receipts. Deliveries already queued for earlier releases still run. There is no route to delete a connection; pause one you no longer use.
Addresses: https and public
Section titled “Addresses: https and public”Colophon calls these addresses from your server, so it refuses any that could reach inside your network. An
address must be https, must not name a private, loopback, link-local or other non-public IP address, and
must not carry a user name or password:
curl -i -X POST "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/destinations" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"kind": "probe", "name": "Home page", "url": "https://192.168.1.20/"}'HTTP/1.1 422 Unprocessable Entitycontent-type: application/jsonx-request-id: 01a1ee89-0d80-703d-9528-10797c328e8econtent-length: 191date: Wed, 18 Nov 2026 12:02:01 GMT
{ "error": { "code": "validation_failed", "message": "192.168.1.20 is not a public address", "details": { "reason": "invalid_url", "pointer": "/url" }, "request_id": "01a1ee89-0d80-703d-9528-10797c328e8e" }}A plain http://localhost:4321/rebuild is refused the same way, with the message
destinations must use https. Every refusal here is 422 validation_failed with details.reason invalid_kind, invalid_name,
invalid_url or invalid_location.
The check is repeated before every attempt, and when a host name is looked up the worker connects only to the
public addresses it resolves to, so a name that later points inside your network is refused then. The worker
never follows a redirect and never goes through a proxy set in its environment (HTTP_PROXY and the like).
What each kind sends
Section titled “What each kind sends”Every request comes from the worker with a 10-second deadline and a User-Agent of colophon/ and the
server’s version.
Site rebuild (webhook)
Section titled “Site rebuild (webhook)”A POST of JSON. For release 2 of the Management API example,
which published the Ginger biscuits, the Site rebuild connection above would receive:
POST /hooks/colophon HTTP/1.1Host: build.example.comContent-Type: application/jsonIdempotency-Key: colophon:01a1ee74-2617-7296-91a0-d6476f0f925b:01a1ee74-2619-7663-85ef-304a7b48ee66:2:01a1ee89-7896-7559-80c7-d436038db473Colophon-Generation: 2
{ "changeset": "01a1ee74-3e10-71a4-9437-e69ddbacdc20", "entries": [ { "collection": "recipes", "id": "01a1ee74-3d83-7045-b45b-71f61ccd9352", "revision_id": "01a1ee74-3dd4-7003-8a3c-94e51101bfda", "title": "Ginger biscuits" } ], "environment": "production", "epoch": 1, "event": "release.committed", "generation": 2, "project": "01a1ee74-2617-7296-91a0-d6476f0f925b", "published_at": 1795001958}| Member | Meaning |
|---|---|
event |
Always release.committed |
project, environment |
The project’s id and the environment’s name |
epoch, generation |
The environment’s epoch (a new one starts only when an operator restores a backup) and the release number |
changeset |
The publish request it published (API: changeset) |
published_at |
When, in seconds since 1970 (UTC) |
entries |
Each entry this release published, with the revision readers now get. Entries it took down aren’t listed: the receipt’s unpublished counts them |
Idempotency-Key is colophon:{project}:{environment}:{generation}:{destination}: the same for every attempt
at one release, so a receiver that keeps the keys it has seen can drop a repeat. A worker that stops halfway
through an attempt makes the attempt again with the same key, so treat the announcement as at least once.
Answer with any 2xx once you have accepted it, and do the rebuild afterwards: a reply slower than 10 seconds
counts as a timeout.
Colophon doesn’t sign the request. To be sure an announcement came from your Colophon, put a long random secret in the URL (a path segment or a query parameter) and have the receiver check it. Only people who manage connections can read the address.
Announcements to one connection go out one at a time and in order: one is never sent after a newer one. If
several releases are waiting, only the newest is sent and the older ones are marked superseded; the newest
release includes their changes, so rebuild from the delivery API rather than from the entries list alone.
Webhooks for other events (entries, media, content types) are Planned.
Cache clear (CDN)
Section titled “Cache clear (CDN)”A POST with the same headers, whose body names the cache tags to drop. For the same release 2:
{ "tags": [ "colophon:p:01a1ee742617729691a0d6476f0f925b:e:01a1ee742619766385ef304a7b48ee66:c:recipes", "colophon:p:01a1ee742617729691a0d6476f0f925b:e:01a1ee742619766385ef304a7b48ee66:n:01a1ee743d837045b45b71f61ccd9352" ]}These are the same tags the delivery API puts in its cache-tag header (see Caching and
ETags): for each entry the releases changed, the entry’s tag, which reaches
every answer that holds it, and its collection’s tag, which reaches every list and query of that content type.
More than 30 tags, and the purge names the environment’s tag alone instead. A purge covers every release since
that connection’s last successful one, so a purge skipped for a newer release is never lost. A release that
changed nothing a CDN could hold sends nothing and counts as done.
Colophon sends this one generic request. Point the connection at an endpoint that accepts it and purges your CDN by tag: your CDN’s own, if it takes this body, or a small function of yours that calls your CDN’s purge-by-tag API.
Site check (probe)
Section titled “Site check (probe)”A GET of the address, with Accept: text/html, application/json. The check reads which release the answer
was built from, in this order:
- a
Colophon-Generationresponse header, or - the first
<meta name="colophon-generation" content="N">in the first megabyte of the body, written exactly so:namebeforecontent, double quotes, digits only.
A 2xx answer that names this release or a later one passes. An older release, or no release at all, means
“not yet”: the check looks again, no sooner than every 5 seconds, up to 10 looks in all. Every look is kept as
an observation on the receipt.
A static site prints the marker in its pages’ <head>, from the release it was built from:
<meta name="colophon-generation" content="2">Point the check at a page of your site, not at the delivery API: the delivery API always sends
Colophon-Generation, so checking it proves only that Colophon serves the release, not that your site was
rebuilt or that its CDN let go of the old copy.
Delivery jobs and retries
Section titled “Delivery jobs and retries”Publishing a release creates one job per connection that is on, in the same database transaction as the release, so a release can’t happen without its jobs or the other way round. The worker runs them:
| The attempt | What happens |
|---|---|
2xx |
Done (succeeded). For a site check, only when it saw the release |
408, 425, 429, 500, 502, 503, 504, a timeout, or no connection |
Tried again |
| Any other status, a redirect included, or an address refused as not public | Given up (failed) at once |
Retries wait a random time up to 1 second, then up to 2, 4 and so on, never more than 60 seconds; a
Retry-After in seconds from your server is honoured up to the same 60. A webhook or cache clear gets 5
attempts, a site check 10. A job not finished an hour after it was created fails.
List the jobs, newest first, optionally for one release:
curl "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/jobs?generation=2" \ -H "Authorization: Bearer $COLOPHON_TOKEN"Each job has id, destination_id, destination_name, generation, status, attempts,
last_http_status, last_error (such as HTTP 503, timed out, could not connect or
saw release 1, not yet 2), created_at and finished_at. The list holds the newest 100 jobs; any member may read it.
status |
Meaning |
|---|---|
pending |
Waiting for its first attempt |
running |
An attempt is in flight |
retrying |
Waiting to be tried again |
succeeded |
Delivered, or the release was seen |
failed |
Refused for good, out of attempts, or out of time |
superseded |
A newer release for the same connection made it unnecessary |
held |
Frozen after a restore from backup until an operator resumes it |
The worker’s timing can be tuned: COLOPHON_WORKER_ATTEMPT_MS (each attempt’s deadline, default 10 s),
COLOPHON_WORKER_SLOTS (attempts in flight, default 8), COLOPHON_WORKER_POLL_MS (default 500 ms) and
COLOPHON_WORKER_LEASE_MS (default 30 s, longer than the attempt deadline). See
Configuration.
The receipt
Section titled “The receipt”Every release has a receipt: what was published, what each connection did, and what each site check saw.
curl "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/releases/1" \ -H "Authorization: Bearer $COLOPHON_TOKEN"{ "data": { "generation": 1, "epoch": 1, "changeset_id": "01a1ee81-1463-72f1-bfd8-7ead078ecf00", "title": "Lemon tart", "changeset_hash": "sha256:b10f7934d85640ce04583516559629c098be811f7c9c8bf6fba1d8bb656511f8", "published_by": "01a1ee81-12ca-7536-9917-c29fb332ce0e", "published_by_name": "Akira Shirase", "published_at": "2026-11-18T11:53:19.3253Z", "entries": 1, "unpublished": 0, "purge": "none", "label": "published", "locations": 0, "deliveries": [], "observations": [] }}This release had no connections, so deliveries and observations are empty and its label is published.
The releases list (GET …/releases) carries the same fields except those two lists.
label: one word for how far it got
Section titled “label: one word for how far it got”label |
In the Studio | Meaning |
|---|---|---|
published |
Published | Live in Colophon. No connection was on, or every connection is done but no site check looked |
pending |
Website update pending | A delivery or a check is still on its way; the label settles by itself |
verified |
Verified at N locations | Every connection is done, and site checks saw this release (or a later one) from locations distinct places |
needs_attention |
Needs attention | A connection gave up on this release |
A failure anywhere outranks everything else, then anything still on its way. A release is never just “verified”: it is verified at the number of places that looked. The Studio shows the label on the Releases page and on each release’s receipt, and for Needs attention says which connection failed and why. The fix is usually to correct the connection’s address or bring the site back, then publish again: the next release carries this one’s changes, and this receipt’s label follows when that one is delivered.
deliveries: each connection’s part
Section titled “deliveries: each connection’s part”| Field | Meaning |
|---|---|
destination_id, name, kind, location |
The connection |
state |
done: its job for this release succeeded. covered: a later release’s job succeeded, which covers this one (covered_by names it). pending: still on its way. failed: gave up |
covered_by |
The release whose delivery covered this one |
status, attempts, last_error, finished_at |
Its job for this very release, if it had one |
observations: what the site checks saw
Section titled “observations: what the site checks saw”One row per look, oldest first: destination_id, location (the worker that looked), observed_generation
(the release the page named, or null), http_status, body_hash (sha256: of what was read), error and
observed_at.
purge: the CDN’s part
Section titled “purge: the CDN’s part”purge |
Meaning |
|---|---|
none |
No cache clear covered this release |
pending |
A purge is on its way: copies the CDN holds may still be served |
accepted |
Every cache clear connection accepted a purge covering it |
failed |
A purge gave up: the CDN may serve old copies until they expire (delivery answers allow shared caches at most 5 minutes) |
accepted means the CDN said yes, not that every edge has dropped the copy; a site check is what shows readers
get the new release. For a release that took entries down, the Studio says Removal pending at the CDN until
the purge is accepted.
Where a site check runs
Section titled “Where a site check runs”Every worker has a location, COLOPHON_WORKER_LOCATION (1 to 63 lowercase letters, digits and dashes;
local by default), and every observation records the location of the worker that made it. A site check with
no location is run by any worker; one with a location only by workers at that location.
To verify a release from more than one place, run a worker in each place, colophon-server --role worker,
each with its own COLOPHON_WORKER_LOCATION (eu-west, us-east), and add a site check pinned to each. A
release both see is Verified at 2 locations.
Was this page helpful?
Either answer opens a short issue on GitHub, so you can say what worked or what was missing.
Colophon home · the product, its blog and how to try it.