Quillet
Menu
Menu

Integrating a site

5 min read

Your site learns that content changed in one of three ways: it asks again after a set time, Quillet tells it with a signed webhook, or you rebuild it.

Why Quillet never pushes content into your site

A publish changes what the delivery API answers at once, but your site may not ask again for a while. Between the two sit caches you own: a framework's data cache, a CDN, the pages a static build wrote. Quillet never pushes content into any of them. Instead it offers three ways for your site to find out that something changed, and each one trades freshness against the work it takes to set up. The table at the end of the next section sets the three side by side.

How your site can hear about a publish

Ask again after a set time

This way needs nothing from Quillet beyond what it already sends. Delivery answers say Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=60, and each one carries an ETag. A client that asks again with If-None-Match gets a 304 with no body when nothing changed, so asking often is cheap.

By default the SDK revalidates on every read, using that ETag. Its Next.js adapter keeps each read in Next's data cache for 60 seconds by default. The trade-off is plain. A publish can take up to that window to show, and in return nothing has to be configured.

Be told, with a webhook

An owner subscribes a URL on your site to events such as content.published, content.unpublished and content.deleted, for every environment or for a chosen few. Quillet writes the webhook's delivery row in the same transaction as the publish, so a committed publish always has its webhook and an aborted one never does. A worker then posts a small JSON envelope to your URL, signed with HMAC-SHA256.

The envelope names what changed: the project, the environment, the keys, the locales and the versions. It never carries content, which keeps it small and safe to log. Your site reads the new content through delivery, with its own key, as it always does. A Next.js site, for example, answers by calling revalidateTag for each key the envelope names.

A webhook arrives at least once, so dedupe on the envelope's id. Webhooks to one endpoint are not ordered either; compare version if order matters to you. When an attempt fails, it is tried again after 1 m, 5 m, 30 m, 2 h and 12 h, and after that the delivery is marked failed. After twenty failed attempts in a row, counted across all its deliveries, the subscription pauses itself. Its row then gives the reason, which reads "Paused after 20 consecutive failed deliveries", with Resume beside it.

Rebuild

A static site reads everything at build time and then serves files. It has no request-time dependency on the CMS, so the CMS can be down and the site still answers. The cost is that a change appears only after the next build. This documentation site works this way, and it is rebuilt by hand. To rebuild on every publish, point a webhook at something that verifies it and starts your build. Quillet itself starts no builds.

Which to choose

Each way trades how soon a publish shows against what you have to set up:

Way Fresh after a publish You set up
Ask again within your cache window nothing
Webhook seconds, while your endpoint answers an endpoint that verifies and revalidates
Rebuild after the build a build, by hand or on a webhook

How to

Dashboard

  1. As an owner, open Settings, then Webhooks, and create a webhook with your endpoint's URL and the content events.
  2. Copy the secret and the verification snippet shown beside it. The secret is shown once.
  3. Press Send test event. The answer is what your endpoint said, in milliseconds.
  4. Publish a document, then open the webhook's deliveries. The newest row is the publish, with its status code.

API

Send the test event to a webhook, with a personal token of one of the project's owners. A CLI key is refused, because webhooks belong to owners.

curl -s -u '<tokenId>:<secret>' -X POST \
  'http://localhost:3000/api/v1/projects/<project>/webhooks/<webhookId>/test'

The answer is the finished delivery: "status":"delivered" and lastCode when your endpoint answered 2xx.

Limits

  • A webhook URL must be https:// and must not resolve to a private address, unless the instance allows either.
  • A project holds at most twenty webhooks, and each one receives at most 60 deliveries a minute; the rest wait.
  • The deliveries log keeps thirty days. A redelivery is a new row with a new id.
  • Quillet sends webhooks and receives none. It delivers over HTTP(S) only, with no queues and no email.
  • The SDK has no helper that verifies a signature. The snippet the dashboard shows uses only Node's crypto.
  • A preview of a draft on your site takes a separate path: a fifteen-minute token per document, read with no-store.
  • Webhooks: events, the envelope, the signature and a receiver.
  • Next.js: the adapter's cache tags and revalidation.
  • Static sites: reading content at build time.
  • Delivery: the cache and the ETag your site revalidates against.
  • Previewing drafts: showing a draft on your own site.

Last updated