Skip to main content
skill CX Codex

vercel-webhooks-events — skill for Claude Code

vercel-webhooks-events — a skill for Claude Code, Codex, Cursor and other platforms that processes Vercel deployment events with HMAC signature verification.

MIT 1 installs ★ 2,935 updated 2026-11-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-webhooks-events -a claude-code
Open on GitHub

What vercel-webhooks-events does

The skill provides a ready-to-use webhook handler with signature verification via the crypto module. It includes functions to handle deployment.created, deployment.ready and deployment.error events, send Slack notifications on successful production deployments, and handle errors. Built-in idempotency prevents double-processing when Vercel retries event delivery.

You need an HTTPS endpoint reachable from the internet and a webhook secret from the Vercel dashboard. The skill uses @vercel/node for request and response types. Test locally with localtunnel or a similar tunnel service, sending curl requests with the correct signature.

The skill works on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Installation varies by platform: npx skills add for Claude Code and Cursor, gh skill install for GitHub Copilot, a separate repository path for Gemini CLI.

What it helps with

  • set up Vercel webhook handling with signature verification
  • send a Slack message when a deployment reaches production
  • prevent the same webhook event from being processed twice
  • test a webhook endpoint locally before deployment
  • distinguish events from Vercel Marketplace integrations and project Deploy Hooks

Example prompts for the agent

  • Set up webhook handling in api/webhooks/vercel.ts with signature verification
  • Send a Slack notification when deployment.ready fires for production
  • Add idempotency to avoid processing the same webhook event twice

How to install vercel-webhooks-events

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-webhooks-events -a claude-code

2Manually: put the files in place

~/.claude/skills/vercel-webhooks-events/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/vercel-webhooks-events/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about vercel-webhooks-events

How do I install vercel-webhooks-events in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-webhooks-events -a claude-code, then check ~/.claude/skills/vercel-webhooks-events/SKILL.md for details.

What does vercel-webhooks-events do?

The skill processes Vercel deployment events (deployment.created, deployment.ready, deployment.error) with HMAC-SHA1 signature verification. It sends notifications, prevents duplicate processing, and includes examples for Slack integration.

Which platforms support this skill?

The skill runs on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Installation differs: npx skills add for most, gh skill install for GitHub Copilot, or a direct repository link for Gemini CLI.

Source text

SKILL.md · MIT
---
name: vercel-webhooks-events
description: 'Implement Vercel webhook handling with signature verification and event
  processing.

  Use when setting up webhook endpoints, processing deployment events,

  or building integrations that react to Vercel deployment lifecycle.

  Trigger with phrases like "vercel webhook", "vercel events",

  "vercel deployment.ready", "handle vercel events", "vercel webhook signature".

  '
allowed-tools: Read, Write, Edit, Bash(curl:*)
version: 1.18.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- vercel
- webhooks
- events
- integration
compatibility: Designed for Claude Code
---
# Vercel Webhooks & Events

## Overview

Handle Vercel webhook events (deployment.created, deployment.ready, deployment.error) with HMAC signature verification. Covers both integration webhooks (Vercel Marketplace) and project-level deploy hooks.

## Prerequisites

- HTTPS endpoint accessible from the internet
- Webhook secret from Vercel dashboard or integration settings
- `crypto` module for HMAC signature verification

## Instructions

### Step 1: Register a Webhook

In the Vercel dashboard:

1. Go to **Settings > Webhooks**
2. Add your endpoint URL (must be HTTPS)
3. Select events to subscribe to
4. Copy the webhook secret for signature verification

Or for Integration webhooks, configure in the Integration Console at `vercel.com/dashboard/integrations`.

### Step 2: Verify Webhook Signature

```typescript
// api/webhooks/vercel.ts
import type { VercelRequest, VercelResponse } from '@vercel/node';
import crypto from 'crypto';

const WEBHOOK_SECRET = process.env.VERCEL_WEBHOOK_SECRET!;

function verifySignature(body: string, signature: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha1', WEBHOOK_SECRET)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  // Get raw body for signature verification
  const rawBody = JSON.stringify(req.body);
  const signature = req.headers['x-vercel-signature'] as string;

  if (!signature || !verifySignature(rawBody, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the event
  const event = req.body;
  await handleEvent(event);

  res.status(200).json({ received: true });
}
```

### Step 3: Handle Deployment Events

```typescript
// lib/webhook-handlers.ts
interface VercelWebhookEvent {
  id: string;
  type: string;
  createdAt: number;
  payload: {
    deployment: {
      id: string;
      name: string;
      url: string;
      meta: Record<string, string>;
    };
    project: {
      id: string;
      name: string;
    };
    target: 'production' | 'preview' | null;
    user: { id: string; email: string; username: string };
  };
}

async function handleEvent(event: VercelWebhookEvent): Promise<void> {
  switch (event.type) {
    case 'deployment.created':
      console.log(`Deployment started: ${event.payload.deployment.url}`);
      // Notify Slack, update status board, etc.
      break;

    case 'deployment.ready':
      console.log(`Deployment ready: ${event.payload.deployment.url}`);
      // Run smoke tests against the deployment URL
      // Notify team of successful deploy
      if (event.payload.target === 'production') {
        await notifyProductionDeploy(event);
      }
      break;

    case 'deployment.error':
      console.error(`Deployment failed: ${event.payload.deployment.id}`);
      // Alert on-call engineer
      // Create incident ticket
      await notifyDeploymentError(event);
      break;

    case 'deployment.canceled':
      console.log(`Deployment canceled: ${event.payload.deployment.id}`);
      break;

    case 'project.created':
      console.log(`New project: ${event.payload.project.name}`);
      break;

    case 'project.removed':
      console.log(`Project removed: ${event.payload.project.name}`);
      break;

    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
}
```

### Step 4: Idempotency — Prevent Duplicate Processing

```typescript
// lib/idempotency.ts
// Vercel may retry webhook delivery — track processed event IDs
const processedEvents = new Set<string>(); // Use Redis in production

async function processWebhookIdempotent(
  event: VercelWebhookEvent,
  handler: (e: VercelWebhookEvent) => Promise<void>
): Promise<boolean> {
  if (processedEvents.has(event.id)) {
    console.log(`Skipping duplicate event: ${event.id}`);
    return false;
  }

  await handler(event);
  processedEvents.add(event.id);
  return true;
}
```

### Step 5: Slack Notification Example

```typescript
// lib/notifications.ts
async function notifyProductionDeploy(event: VercelWebhookEvent): Promise<void> {
  const { deployment, project, user } = event.payload;

  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `Production deploy complete`,
      blocks: [
        {
          type: 'section',
          text: {
            type: 'mrkdwn',
            text: [
              `*${project.name}* deployed to production`,
              `By: ${user.username}`,
              `URL: https://${deployment.url}`,
              `Commit: ${deployment.meta?.githubCommitMessage ?? 'N/A'}`,
            ].join('\n'),
          },
        },
      ],
    }),
  });
}

async function notifyDeploymentError(event: VercelWebhookEvent): Promise<void> {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `Deployment FAILED for ${event.payload.project.name} — ${event.payload.deployment.id}`,
    }),
  });
}
```

### Step 6: Test Webhooks Locally

```bash
# Use the Vercel CLI to test webhook signatures
# Or use a tunnel service for local testing
npx localtunnel --port 3000
# Gives you a public URL like https://xxx.loca.lt

# Send a test webhook payload
curl -X POST http://localhost:3000/api/webhooks/vercel \
  -H "Content-Type: application/json" \
  -H "x-vercel-signature: $(echo -n '{"type":"deployment.ready","id":"test"}' | openssl dgst -sha1 -hmac 'your-secret' | awk '{print $2}')" \
  -d '{"type":"deployment.ready","id":"test"}'
```

## Webhook Event Types

| Event | Trigger |
|-------|---------|
| `deployment.created` | New deployment started building |
| `deployment.ready` | Deployment build completed successfully |
| `deployment.error` | Deployment build failed |
| `deployment.canceled` | Deployment was canceled |
| `project.created` | New project created |
| `project.removed` | Project deleted |
| `domain.created` | Domain added to project |
| `integration.configuration.removed` | Integration uninstalled |

## Output

- Webhook endpoint with HMAC signature verification
- Event handlers for deployment lifecycle events
- Idempotent processing preventing duplicates
- Slack notifications for production deploys and failures

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `401 Invalid signature` | Wrong webhook secret or body mismatch | Verify secret matches dashboard, use raw body for HMAC |
| Webhook not received | Endpoint not publicly accessible | Ensure HTTPS, check firewall rules |
| Duplicate processing | Webhook retried by Vercel | Implement idempotency with event ID tracking |
| `504 timeout` on webhook endpoint | Handler takes too long | Return 200 immediately, process async in background |
| Missing `x-vercel-signature` | Not a real Vercel webhook | Reject requests without the signature header |

## Examples

### Process a deployment webhook exactly once

Verify the raw-body HMAC signature before parsing the event, reject absent or invalid signatures with a generic response, and persist the event ID in an idempotency store before any side effect. Acknowledge quickly and hand longer work to a controlled background queue. Test duplicate delivery and an invalid signature with synthetic events in preview, and keep notification payloads free of tokens, environment values, and customer request data.

## Resources

- [Vercel Webhooks API](https://vercel.com/docs/webhooks/webhooks-api)
- [Setting Up Webhooks](https://vercel.com/docs/webhooks)
- [Deploy Hooks](https://vercel.com/docs/deploy-hooks)
- [Integration Webhooks](https://vercel.com/docs/integrations/create-integration)

## Next Steps

For performance optimization, see `vercel-performance-tuning`.

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
cursor-usage-analytics cursor-usage-analytics analyzes aggregated Cursor usage across requests, models, spend, and team adoption. Use it to prepare reports and review quota signals. CX Codex +1 1installs customerio-cost-tuning customerio-cost-tuning audits a Customer.io workspace for wasted spend: which profiles inflate the bill, which accounts can go, where duplicate events pile up. CX Codex +1 1installs apollo-core-workflow-a apollo-core-workflow-a builds an Apollo.io lead generation pipeline in Claude Code to search prospects and enrich qualified contacts with verified emails and phone numbers. CX Codex +1 1installs firecrawl-migration-deep-dive The firecrawl-migration-deep-dive skill guides a move from Puppeteer, Playwright, Cheerio, or another scraper to Firecrawl v2, with checks for parity, policy, spend, and rollback. CX Codex +1 1installs vercel-reference-architecture vercel-reference-architecture sets up a layered Vercel architecture for Next.js applications. Helps structure edge middleware, serverless API routes, and environment validation. CX Codex +1 1installs vercel-policy-guardrails The vercel-policy-guardrails skill adds Vercel project checks for secret exposure, CI policy violations, Edge Runtime imports, and protected routes. CX Codex +1 1installs gcs-lifecycle-policy gcs-lifecycle-policy — a skill that handles lifecycle policy work in Google Cloud Storage. It activates on its own when a request mentions gcs or lifecycle policy. CX Codex +1 1installs gcs-bucket-config gcs-bucket-config automates Google Cloud Storage bucket configuration in Claude Code. Generates configs and gcloud commands for your storage setups. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open