Vercel Integration
Link deployments to issues with preview URLs and status badges.
Setup
Go to Settings → Integrations and click Connecton the Vercel card. You will be redirected to Vercel to authorize the Velocity integration for your team or personal account.
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:
| Event | Action |
|---|---|
deployment.created | Records that a deployment has started building |
deployment.succeeded | Updates status to ready, auto-comments with preview URL |
deployment.error | Updates status to failed, auto-comments with link to logs |
deployment.canceled | Records cancellation |
deployment.ready | Attaches final production URL for production deploys |
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)
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
- Link preview URLs — Attach Vercel preview URLs to issues
- Show deploy badges — Display deployment status on issues
- Default team — Assign deployment events to a team when no issue link is found
Webhook Setup
After connecting via OAuth, configure a webhook in your Vercel project settings. The webhook URL and signing secret are shown on the integration settings page in Velocity. Point your Vercel webhook to:
https://velocity.quest/api/webhooks/vercelSecurity
Incoming webhooks are verified using HMAC-SHA256 signature validation. The X-Vercel-Signature header is checked against the webhook secret generated during setup. Invalid signatures are rejected with a 401 response.