Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Vercel to Fondoo

Live5 min readUpdated

Connecting Vercel lets Fondoo set up the Vercel project that hosts your app, so it works alongside your Fondoo marketing site. Fondoo adds your app's custom hostname to the project and sets a few public environment variables. It also registers a deployment webhook, so each production deploy can become changelog, blog, social and newsletter drafts for your AI agent to work on.

What Fondoo can do with it

After you connect Vercel, running connect_app with host:"vercel" does three things:

  • Adds a domain. It adds the planned app hostname (normally app.<your domain>) to your Vercel project and reports any verification records Vercel asks for.
  • Sets environment variables. It sets these public, non-secret variables for the production environment: FONDOO_SITE_ID and FONDOO_API_BASE, each with the prefixes NEXT_PUBLIC_, VITE_, PUBLIC_ and NUXT_PUBLIC_. The site ID is a public value, not a secret.
  • Registers a deployment webhook. It points to Fondoo for the events deployment.ready and deployment.succeeded on that project.

After that:

  • Fondoo checks the project during get_connection_health.
  • Verified production deploys feed Fondoo's release-content pipeline. Preview deploys are ignored, and repeat deliveries are de-duplicated.

Fondoo never triggers a deployment, never edits your code and never merges anything. Saving the Vercel token is an owner-only action: an agent cannot do it on its own key. connect_app is an ordinary write that agents can run.

Before you start

  • A Vercel account and the project that hosts your app. Vercel's Hobby plan is free; paid plans are listed on Vercel's pricing page.
  • Webhooks need a Pro or Enterprise plan. Vercel states that account webhooks are available on Enterprise and Pro plans (Vercel webhooks). On Hobby, the webhook step of connect_app may fail. This may differ for your account.
  • A Fondoo site and your app's public URL at Vercel, for example https://my-app.vercel.app.
  • Owner access in Fondoo. You must be signed in as the workspace owner to save the token.

Step by step: get your credentials

You need three values: an access token, the project ID and (for team projects) the team ID.

  1. Create a token.
    1. Open the Account Tokens page in your Vercel account settings: https://vercel.com/account/tokens .
    2. Enter a name, for example "Fondoo".
    3. Under Scope, choose the team that owns the project. Vercel also offers project-scoped tokens. A project-scoped token may not be allowed to create the team-level webhook, so the team scope is the safer choice. This may differ for your account.
    4. Choose an expiration, select Create, and copy the token. It starts with vcp_ and is shown only once (Vercel access tokens).
    5. Some teams require two-factor authentication or SAML before you can create a token for them.
  2. Find the project ID. Open the project, then Settings → General → Project ID. It starts with prj_ (project settings).
  3. Find the team ID. Open the team dashboard, then Settings → General → Team ID (find your team ID). Fondoo sends this as teamId on every Vercel request. Leave it out for a personal (non-team) project.

Connect it in Fondoo

In the dashboard:

  1. Open Connections.
  2. Under Available → Development, find Vercel and click Connect Vercel.
  3. Fondoo shows Connect securely. This link (valid for 15 minutes) explains the steps. It does not collect the token.
  4. Save the token yourself with configure_host_connection, as below.

By asking your agent. For example:

"Connect my app at https://my-app.vercel.app to Fondoo and set up Vercel."

The agent can call connect_service({provider:"vercel", siteId}) to get you the setup link. You, as owner, then save the token:

configure_host_connection({siteId, provider:"vercel", projectId:"prj_...", accountId:"team_...", token:"vcp_..."})

Then the agent runs:

connect_app({siteId, appUrl:"https://my-app.vercel.app", host:"vercel"})

This is not the add_connection_key secure paste flow. The token travels inside the call, so do not paste it into an agent chat, because chat logs may keep it. Run it over REST from your own terminal instead:

POST https://api.getfondoo.com/v1/ops/configure_host_connection
Authorization: Bearer <owner credential>
{"siteId":"...","provider":"vercel","projectId":"prj_...","accountId":"team_...","token":"vcp_..."}

Before saving, Fondoo reads the project once (GET /v9/projects/{id}). A wrong token or ID is rejected straight away.

Webhooks

You do not create this webhook by hand. connect_app registers it through Vercel's API:

  • URL: https://api.getfondoo.com/webhooks/hosts/<connectionId>
  • Events: deployment.ready and deployment.succeeded
  • Scope: your project ID only

Vercel returns a signing secret when the webhook is created. Fondoo stores it encrypted. Every delivery is checked against the x-vercel-signature header, which is an HMAC-SHA1 hex digest of the raw body (securing webhooks). Unsigned or mismatched deliveries are rejected.

You can see the webhook under your team's Settings → Webhooks. Vercel allows 20 custom webhooks per team.

Test that it works

  1. Run get_connection_health({siteId}). The Vercel entry should show a recent success.
  2. In Vercel, check Settings → Environment Variables for NEXT_PUBLIC_FONDOO_SITE_ID and the other entries.
  3. Check Settings → Domains for the app hostname. Complete any verification Vercel shows, then add the DNS records from the connect_app routing plan.
  4. Deploy to production. Then get_release_content should show the new deployment, provided release jobs are enabled on your Fondoo server.

Troubleshooting

  • "Host request failed (401)" or "(403)". The token is wrong, expired, or scoped to a different team. Create a new token scoped to the project's team.
  • "Host request failed (404)". The project ID is wrong, or the team ID is missing or incorrect for a team project.
  • The webhook step fails. Check your plan (webhooks need Pro or Enterprise) and the token scope. A team can only have 20 webhooks.
  • "Host request failed (429)". You hit a Vercel rate limit, for example 100 domain changes or 120 environment-variable writes per 60 seconds (Vercel limits). Wait a minute and retry.
  • Variables missing in the running app. Vercel applies new variables on the next deployment. Fondoo does not redeploy for you.
  • "Host connector is not configured". The Vercel integration is not enabled on this Fondoo server. Contact your Fondoo operator.

Limits, data and security

  • What Fondoo stores: the token and webhook secret, encrypted, plus the project and team IDs and the last success or error. The token is never shown back to you.
  • Rotate: create a new Vercel token, then run configure_host_connection again with the same project. The existing webhook is kept. Pointing it at a different project clears the stored webhook so connect_app can register a new one.
  • Disconnect: Fondoo has no operation that deletes a host connection. To stop access:
    1. Revoke the token on the Account Tokens page.
    2. Delete the Fondoo webhook under Settings → Webhooks.
    3. Optionally, remove the FONDOO_ variables and the app domain.