Vercel

What your agents can doCopy Anchor Link

Agents can call Vercel REST API endpoints for deployments, projects, environment variables, domains, and feature flags. Helios attaches the connection's token to requests. Access depends on the token's permissions.

• Read the build logs of a failed deployment and explain what broke
• List projects and deployments and report their state
• Redeploy a deployment, promote one to production, or roll back
• Read and change environment variables
• Check domains, DNS records, and certificates
• Read and change feature flags

Agents can call only api.vercel.com. Vercel Blob, Edge Config reads, and AI Gateway run on other hosts with their own tokens, so agents can't reach them. Agents can send files of up to 16 MB, such as deployment files to POST /v2/files.

With Your own Vercel OAuth app, an agent can reach only the endpoints that the integration's API scopes cover, and only the projects you gave it access to when you installed it.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

The two methods receive different trigger events. See Triggers.

Vercel Access TokenCopy Anchor Link

A Vercel access token has no permission settings. It acts with the role of the member who created it, within the scope you choose. For full access, create it as a team Owner. A Member can't change billing or invite users, and a Developer can't change production environment variables. Triggers need a team on Vercel's Pro or Enterprise plan, because Vercel offers account webhooks only on those plans.

1. In Vercel, open the Account Tokens page in your account settings.
2. Enter a name. Under Scope, choose the team the agents should work in and select All Projects, or choose Full Account.
3. Choose an expiration and click Create. Copy the token. Vercel shows it only once.
4. In Helios, choose Vercel Access Token and paste the token into Vercel Access Token.
5. If the token is a Full Account token, enter the team ID (team_..., from the team's Settings → General page) or the team slug in Team ID or slug. Without it, Helios works in your personal account. A token scoped to a team needs no team ID.
6. Save.

A token scoped to a single project can't manage the team's webhooks, so triggers don't work with it. When the token expires, create a new one and enter it through Manage.

Your own Vercel OAuth appCopy Anchor Link

In Vercel, an OAuth app is an integration that you create in the Integrations Console. Installing it gives Helios a long-lived token for the team or account you install it on. Vercel issues no refresh token.

1. In Vercel, open Integrations in the sidebar, click Integrations Console, and click Create.

2. Fill in the form. It asks for a name, a URL Slug, a logo, contact details, and links to your terms and privacy policy.

3. Set Redirect URL to:

   Copy Text

   https://api.heliosapp.com/integrations/vercel/oauth_callback

4. Under API Scopes, give the integration every scope at its highest level:

   Scope	Level	What it allows
   Integration Configuration	Read/Write	Read the installation, and remove it
   Deployments	Read/Write	Read deployments and build logs, and create, change, and delete deployments
   Deployment Checks	Read/Write	Read, create, and update checks on deployments
   Projects	Read/Write	Read projects and their domains, and create, change, and delete projects
   Project Environment Variables	Read/Write	Manage the environment variables the integration created
   Global Project Environment Variables	Read/Write	Manage all environment variables in the team or account
   Teams	Read	Read the team and its members
   Current User	Read	Read the Hobby account the integration is installed on
   Drains	Read/Write	Read, create, and update Drains on Pro and Enterprise teams
   Domain	Read/Write	Read domains, their status and configuration, and remove domains

5. Leave Webhook URL empty for now, and save the integration.

6. Copy the client ID and client secret from the Credentials section of the integration's settings.

7. In Helios, choose Your own Vercel OAuth app. Fill in Client ID and Client Secret, and enter the integration's URL slug in Integration URL slug.

8. Save. Helios opens the integration's install page in Vercel. Choose the team, give the integration access to all projects, finish the installation, and Vercel returns you to Helios.

Vercel takes the scopes from the Integrations Console, not from Helios, and it marks none of them as admin-only. So this method has no Admin access option. Vercel's permission list has no scope for feature flags, the firewall, Edge Config, or Sandbox. Use Vercel Access Token when agents need those.

If you change the scopes later, Vercel notifies the team's owners, and the new scopes apply once they confirm them. If you rotate the secret with Rotate Secret, enter the new one in Client Secret through Manage and save. Vercel disables an installation when the member who installed it leaves the team. Connect again as a current member.

TriggersCopy Anchor Link

Vercel can start a Workflow when something changes in your team. How events reach Helios depends on the method, and each method receives a different set of events. The trigger picker shows the events a connection can't receive as unavailable, with the reason.

With Vercel Access TokenCopy Anchor Link

Helios creates an account webhook in the team when you save the connection, so there is nothing to set up in Vercel. The webhook covers every project in the team and requests the supported account webhook events. Deleting the connection removes the webhook.

This needs a team on the Pro or Enterprise plan, and a token scoped to that team or to the full account. On a Hobby team, agents can still use the connection, but no events reach Helios. Vercel allows up to 20 account webhooks per team, and each Helios connection uses one. If Vercel refuses an event, Helios creates the webhook again without that event and the events with undocumented payloads. The trigger picker shows every event left out of the webhook as unavailable.

With your own Vercel OAuth appCopy Anchor Link

Helios doesn't create an account webhook for an OAuth app connection. Point the integration's own webhook at Helios instead. Vercel signs these deliveries with the integration's client secret, which Helios already has.

1. In Helios, open the Vercel connection, click Manage, and open Advanced Configuration. Copy the URL under Webhook Setup.
2. In the Vercel Integrations Console, open the integration's settings.
3. Paste the URL into Webhook URL, and select every event the console offers.
4. Save.

An integration has one webhook URL, so only one Helios connection can receive its events. Helios accepts only deliveries for the installation or owner saved during OAuth. Connect the app again if those details are missing or the installation moves to another team. Vercel sends project.created and project.removed to an integration only when it has access to all projects.

Events for both methodsCopy Anchor Link

Events for Vercel Access Token onlyCopy Anchor Link

The Integrations Console doesn't offer these events for an integration's webhook.

Events with undocumented payloadsCopy Anchor Link

Vercel accepts these events for account webhooks but doesn't document their payloads, so they have no filters and a run gets the payload as Vercel sent it. Only Vercel Access Token receives them.

Events for your own Vercel OAuth app onlyCopy Anchor Link

Vercel sends these events only to an integration's webhook. The invoice, member, resource, and deployment action events come from Marketplace native integrations.

Vercel's event namesCopy Anchor Link

Some events have a different name in Vercel:

• deployment.failed is deployment.error, deployment.built is deployment.ready, deployment.rolled_back is deployment.rollback, and deployment.deleted is deployment.cleanup.
• deployment_check.rerequested is deployment.check-rerequested, and deployment_action.* is deployment.integration.action.*.
• The domain.* and certificate.* events are Vercel's domain.* events, such as domain.renewal and domain.certificate-add.
• project_domain.*, env_variable.*, and rolling_release.* are project.domain.*, project.env-variable.*, and project.rolling-release.*.
• flag_segment.* is flag.segment.*, alert.triggered is alerts.triggered, and attack.detected is firewall.attack.
• installation.* is integration-configuration.*, resource.* is integration-resource.*, invoice.* is marketplace.invoice.*, and invoice.payment_failed is marketplace.invoice.notpaid. installation_member.changed is marketplace.member.changed.
• For the events with undocumented payloads, Helios replaces Vercel's dashes with underscores, as in edge_config.created for edge-config.created. These differ more: deployment.check_run_started and deployment.check_run_canceled are deployment.checkrun.start and deployment.checkrun.cancel, deployment.checks_failed and deployment.checks_succeeded are deployment.checks.failed and deployment.checks.succeeded, edge_config.items_updated is edge-config.items.updated, and ai_gateway.auto_reload_limit_reached is ai-gateway.auto-reload.limit-reached.
• The *_detected events are Vercel's firewall.system-rule-anomaly, firewall.custom-rule-anomaly, observability.anomaly, observability.anomaly-error, observability.usage-anomaly, observability.error-anomaly, and botid.anomaly. webhook.tested is test-webhook.

FiltersCopy Anchor Link

All filters are optional. An empty filter matches every event. Pattern filters are case sensitive, and * matches any text except /.

• Project matches the project the event belongs to, chosen from a list of your projects. For project_domain.moved, it matches either project.
• Environment is Production or Preview. Preview matches deployments whose target is preview or null. Other named environments do not match Preview.
• Branch matches the Git branch the deployment was built from, such as main or feature/*. Helios reads it from the deployment's githubCommitRef, gitlabCommitRef, or bitbucketCommitRef metadata. A deployment without Git metadata, such as one made through the API, has no branch, so a branch filter skips it.
• Domain matches any domain name in the event, such as *.example.com. That includes the old and new name of an updated project domain, the DNS zone of a DNS change, and the names on a certificate.
• Flag and Segment match the slug of the feature flag or flag segment, such as checkout-*.
• Severity is Low, Medium, High, or Critical. Vercel sets Critical only after a Vercel Agent investigation.

Deliveries are verified with the HMAC-SHA1 x-vercel-signature header. Vercel retries a failed delivery for up to 24 hours. Deliveries more than 24 hours old are rejected, and a delivery that Vercel retries is processed once.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means Vercel rejected the token, or the team ID or slug is wrong.
• The webhook: with Vercel Access Token, open the team's Settings → Webhooks in Vercel. A webhook with the connection's Helios URL should be listed. With your own OAuth app, check Webhook URL and the selected events in the integration's settings.
• A trigger:
  1. Add deployment.created to a workflow with no filters.
  2. Push a commit to a project, or redeploy one.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Account webhooks need a Pro or Enterprise team, and a team can have up to 20 of them. See Vercel's webhooks docs.