Deploy hooks

A static site built from BuildBase content needs a rebuild to show what changed. A deploy hook is a URL your hosting provider creates for exactly that. When you start a deploy in the BuildBase console, BuildBase calls the hook and your provider starts a build.

Publishing a post does not start a deploy on its own. You start one from the banner at the top of the console, or with Deploy on a hook: Starting a deploy shows both. To rebuild on every publish instead, point a content webhook at a small function of yours that calls the hook: Delivering content shows how.

What it is for

How it works

Trigger. Starting a deploy calls the hook with a POST. The provider answers that the build is queued, and BuildBase records the deploy in the history. If the hook answers with an error, nothing is recorded and the console says which hook refused and what it answered.

Report back, on Vercel. Vercel can send each deployment's result to BuildBase through an account webhook. BuildBase checks the signature against the secret you saved on the hook, ties the event to the deploy that started it, and moves the deploy from Pending to Success, Failed or Canceled. Vercel offers account webhooks on Pro and Enterprise teams.

Other providers. Netlify, Cloudflare Pages and Render start builds the same way. BuildBase does not receive their results, so their deploys read Triggered (or Queued, when Render waits for a deploy already running): the hook was called, and you check the build at the provider.

Starting a deploy

When published blog posts change, a banner at the top of the console says how many:

1. Select Preview changes. The Changes preview dialog lists the posts that changed since the last deploy.
2. Open the hook picker (it reads Choose a hook to deploy until you pick one) and choose the site to rebuild. A hook that already has the current content reads (Up to date) and cannot be chosen.
3. Select Confirm and publish.

The banner also shows when a hook has not deployed the current content yet, for example right after you add one, or after a published post is unpublished or deleted. It then reads "A deploy hook has not published the current content yet.", and Changes preview lists no posts, only the hooks:

It shows again when a Vercel hook's latest build fails or is canceled, if the hook reports its results (the webhook in part 3 of the Vercel setup). That content never went live, so the hook goes back to the content it had before the failed build: the banner offers the new content again, and the hook is no longer marked (Up to date). The posts count as published once a deploy has started, so the banner reads "A deploy hook has not published the current content yet." and lists no posts. A build that fails on content the hook already had changes nothing, because that content is still live. Coming back to the console's tab is enough for the banner to notice.

The banner only watches blog posts, and a deploy always rebuilds the whole site. After any other change, open Settings > Deploy hooks, select Manage hooks, and select Deploy on the hook.

Two URLs, opposite directions

The most common mistake is to paste one of these where the other goes. The console refuses the status URL pasted as a deploy hook. It cannot see the opposite mistake: a deploy hook URL pasted into Vercel's Endpoint starts a new build on every event Vercel sends, so check that field yourself.

A deploy hook URL is a credential: anyone who has it can start a build of your site. Keep it out of code and screenshots. If it leaks, delete the hook at your provider and create a new one (on Render, select Regenerate Hook), then delete the old hook in BuildBase and add the new URL. On a Vercel hook that reports its results, paste the same webhook secret into Vercel webhook secret when you add it, or its deploys read Triggered from then on (Adding the secret later covers a lost one). Deleting a hook in BuildBase does not delete it at the provider.

Reading the status

Each deploy in Settings > Deploy hooks has a badge:

A Render deploy also has an Open in Render link under its badge, which opens the deploy in your Render dashboard. View response shows what the hook answered, and with which HTTP status.

A deploy whose hook was deleted shows Deleted in the Hook column. A Vercel deploy that was still Pending when its hook was deleted can no longer hear back, and ends as No result yet: check it in Vercel.

Each hook in Manage hooks has a deploy status:

Setup guide, at the top of Settings > Deploy hooks and of Manage hooks, has the same steps as these pages inside the console, with the BuildBase status URL to copy.

Plan limits and permissions

Your plan sets how many hooks you can add, shown beside Create hook, and how many deploys you can start a month. A deploy counts once the provider accepts the call; a hook that refuses it does not use one up. Publishing to your site is a plan feature of its own: without it, Deploy and Confirm and publish are locked.

The banner and Deploy need the deploy hooks permission on your role. The deployment history is a separate permission, so someone who can deploy may not see the history, and the other way round.

Next steps

• Set up a Vercel deploy hook - the deploy hook, the status webhook, and how to check both work
• Set up a Netlify, Cloudflare Pages or Render deploy hook - where each provider keeps its hook
• Delivering content - pull content into your build, or rebuild on every publish with a content webhook that calls the hook