Vercel Integration

Link deployments to issues, with a comment when they go live or fail.

Setup

Velocity receives deployments through a Vercel account webhook, which needs a Vercel Pro or Enterprise team. Velocity asks for no Vercel token and calls no Vercel API.

1. In Velocity, go to Settings → Integrations and click Connect on the Vercel card. The setup page shows your Velocity webhook URL. Only workspace admins and owners can connect an integration.
2. In Vercel, open Team Settings → Webhooks and create a webhook with that URL (see Webhook Setup).
3. Vercel shows the webhook's secret once, when it is created. Copy it, paste it into the setup page in Velocity, and click Save & Connect.

How It Works

Once connected, Velocity listens for Vercel deployment webhooks. When a deployment is triggered from a branch or commit that references a Velocity issue identifier (e.g., ENG-42), the deployment is automatically linked to that issue.

Issue identifiers are extracted from:

• Git branch names (e.g., feat/ENG-42-add-auth)
• Commit messages (e.g., Fix pagination bug ENG-42)

Deployment Events

Velocity processes the following Vercel webhook events:

Auto-Comments

When a deployment succeeds or fails, Velocity automatically posts a comment on the linked issue with:

• Project name and environment (production or preview)
• Branch and commit SHA
• Direct link to the deployed site (on success)
• Link to deployment logs (on failure)

Vercel retries a delivery it thinks failed, so the same event can arrive twice, and not always in order. Velocity comments only when a deployment's status changes, so a retry never posts a second comment, and a late event never moves a finished deployment back to building. Auto-comments can be disabled from the integration settings page.

Configuration Options

After connecting, configure the integration from Settings → Integrations → Vercel:

• Auto-comment — Post comments on issues when deployments complete

Webhook Setup

Webhooks are created per team, not in project settings: in Vercel, open Team Settings → Webhooks and create a webhook. Account webhooks are available on the Pro and Enterprise plans.

• Events: deployment.created, deployment.succeeded, deployment.error and deployment.canceled.
• Projects: the projects whose deployments Velocity should track.
• Endpoint URL: the one the setup page in Velocity shows:

https://velocity.quest/api/webhooks/vercel

Once connected, the Vercel settings page shows the same URL with ?integrationId=<id> added. Either works: Velocity identifies the integration by the delivery's signature, so a webhook made with the URL from setup doesn't need changing.

When you create the webhook, Vercel shows its secret once. Paste it into Velocity straight away: Vercel won't show it again, and Velocity never displays it after saving.

To change the secret, create a new webhook in Vercel, then use Replace secret on the Vercel settings page in Velocity and paste the new webhook's secret. You choose how long the old secret keeps working (24 hours by default), so the old webhook's deliveries aren't refused while both exist. An event both webhooks send is recorded, and commented on, once. Delete the old webhook in Vercel afterwards.

Security

Vercel signs every delivery: the x-vercel-signature header carries an HMAC-SHA1 of the raw request body, keyed with the webhook's secret. Velocity checks it against the secret you pasted before reading the body, and rejects a missing or invalid signature with a 401 response.

The secret is stored write-only: no one can read it back from Velocity, and the audit log records who set or replaced it, never the value.