Vercel

The Vercel integration connects your deployments with Almirant, allowing you to see preview URLs directly on work items and track the status of each deployment without leaving the platform.

How it works

The integration relies on a Vercel webhook that notifies Almirant every time a deployment occurs. When Vercel deploys a new version of your application, it sends an event to the Almirant webhook with the deployment information, including the preview URL and status.

Vercel deploys --> Webhook notifies Almirant --> Almirant updates the work item

Setting up the integration

1. Obtain the webhook secret

An administrator in your organization must configure the VERCEL_WEBHOOK_SECRET environment variable in the Almirant backend. This secret is used to verify that notifications actually come from Vercel.

2. Configure the webhook in Vercel

1. Go to your project in the Vercel dashboard.
2. Navigate to Settings > Webhooks.
3. Click Create Webhook.
4. Configure the following fields:

Field	Value
URL	https://your-almirant-domain.com/webhooks/vercel
Secret	The same value configured in VERCEL_WEBHOOK_SECRET
Events	deployment.created, deployment.succeeded, deployment.failed, deployment.canceled

5. Save the webhook.

3. Verify the connection

Perform a test deployment on Vercel and verify that Almirant receives the notification. You can check the webhook logs in Almirant's settings.

Preview URLs on work items

When a Vercel deployment is linked to a work item (through the reference in the commit or branch), Almirant displays the preview URL directly on the work item detail view. This allows team members to quickly access the preview environment to review changes.

Visible information

On each work item linked to a deployment, you'll see:

Data	Description
Preview URL	Direct link to the preview deployment
Status	Deployment status (building, ready, error, canceled)
Branch	Git branch from which the deployment was made
Date	Date and time of the deployment

Deployment statuses

Almirant reflects Vercel deployment statuses in real time:

Status	Meaning
Building	The deployment is in progress
Ready	The deployment completed successfully and the preview URL is available
Error	The deployment failed during the build process
Canceled	The deployment was manually canceled

Best practices

Branch names

Use branch names that include the work item identifier (for example feature/A-T-42-notifications) so that Almirant automatically links deployments to the corresponding work item.

• Configure webhooks per project -- If you have multiple projects on Vercel, set up a webhook for each one pointing to the same Almirant endpoint.
• Use the webhook secret -- Always configure a secret to verify the authenticity of notifications.
• Monitor the logs -- Periodically check the webhook logs to detect communication errors.

For Developers

Environment variable

Variable	Description	Required
VERCEL_WEBHOOK_SECRET	Shared secret used to verify the signature of Vercel webhooks	Yes

Webhook endpoint

The endpoint that receives Vercel notifications is:

POST /webhooks/vercel
Headers:
  x-vercel-signature: <hmac-signature>
Body: JSON with the deployment event payload

The backend verifies the HMAC signature of the payload using VERCEL_WEBHOOK_SECRET before processing the event. If the signature does not match, the webhook is rejected with a 401.

Processing flow

1. Vercel sends the event to the /webhooks/vercel endpoint.
2. The backend verifies the HMAC signature of the payload.
3. Deployment information is extracted (URL, status, branch, commit).
4. If the commit or branch contains a reference to a work item, it is automatically linked.
5. The deployment information is stored and displayed on the work item detail view.