@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-webhooks-events/SKILL.md

@@ -1,199 +1,275 @@
 ---
 name: vercel-webhooks-events
-description: |
-  Implement Vercel webhook signature validation and event handling.
-  Use when setting up webhook endpoints, implementing signature verification,
-  or handling Vercel event notifications securely.
+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 webhook signature", "handle vercel events", "vercel notifications".
+
+  "vercel deployment.ready", "handle vercel events", "vercel webhook signature".
+
+  '
 allowed-tools: Read, Write, Edit, Bash(curl:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- webhooks
+- events
+- integration
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Webhooks & Events
 
 ## Overview
-Securely handle Vercel webhooks with signature validation and replay protection.
 
-## Prerequisites
-- Vercel webhook secret configured
-- HTTPS endpoint accessible from internet
-- Understanding of cryptographic signatures
-- Redis or database for idempotency (optional)
+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.
 
-## Webhook Endpoint Setup
+## Prerequisites
 
-### Express.js
-```typescript
-import express from 'express';
-import crypto from 'crypto';
+- HTTPS endpoint accessible from the internet
+- Webhook secret from Vercel dashboard or integration settings
+- `crypto` module for HMAC signature verification
 
-const app = express();
+## Instructions
 
-// IMPORTANT: Raw body needed for signature verification
-app.post('/webhooks/vercel',
-  express.raw({ type: 'application/json' }),
-  async (req, res) => {
-    const signature = req.headers['x-vercel-signature'] as string;
-    const timestamp = req.headers['x-vercel-timestamp'] as string;
+### Step 1: Register a Webhook
 
-    if (!verifyVercelSignature(req.body, signature, timestamp)) {
-      return res.status(401).json({ error: 'Invalid signature' });
-    }
+In the Vercel dashboard:
 
-    const event = JSON.parse(req.body.toString());
-    await handleVercelEvent(event);
+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
 
-    res.status(200).json({ received: true });
-  }
-);
-```
+Or for Integration webhooks, configure in the Integration Console at `vercel.com/dashboard/integrations`.
 
-## Signature Verification
+### Step 2: Verify Webhook Signature
 
 ```typescript
-function verifyVercelSignature(
-  payload: Buffer,
-  signature: string,
-  timestamp: string
-): boolean {
-  const secret = process.env.VERCEL_WEBHOOK_SECRET!;
-
-  // Reject old timestamps (replay attack protection)
-  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
-  if (timestampAge > 300000) { // 5 minutes
-    console.error('Webhook timestamp too old');
-    return false;
-  }
+// api/webhooks/vercel.ts
+import type { VercelRequest, VercelResponse } from '@vercel/node';
+import crypto from 'crypto';
 
-  // Compute expected signature
-  const signedPayload = `${timestamp}.${payload.toString()}`;
+const WEBHOOK_SECRET = process.env.VERCEL_WEBHOOK_SECRET!;
+
+function verifySignature(body: string, signature: string): boolean {
   const expectedSignature = crypto
-    .createHmac('sha256', secret)
-    .update(signedPayload)
+    .createHmac('sha1', WEBHOOK_SECRET)
+    .update(body)
     .digest('hex');
-
-  // Timing-safe comparison
   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 });
+}
 ```
 
-## Event Handler Pattern
+### Step 3: Handle Deployment Events
 
 ```typescript
-type VercelEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';
-
-interface VercelEvent {
+// lib/webhook-handlers.ts
+interface VercelWebhookEvent {
   id: string;
-  type: VercelEventType;
-  data: Record<string, any>;
-  created: 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 };
+  };
 }
 
-const eventHandlers: Record<VercelEventType, (data: any) => Promise<void>> = {
-  'resource.created': async (data) => { /* handle */ },
-  'resource.updated': async (data) => { /* handle */ },
-  'resource.deleted': async (data) => { /* handle */ }
-};
+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}`);
+  }
+}
+```
 
-async function handleVercelEvent(event: VercelEvent): Promise<void> {
-  const handler = eventHandlers[event.type];
+### Step 4: Idempotency — Prevent Duplicate Processing
 
-  if (!handler) {
-    console.log(`Unhandled event type: ${event.type}`);
-    return;
+```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;
   }
 
-  try {
-    await handler(event.data);
-    console.log(`Processed ${event.type}: ${event.id}`);
-  } catch (error) {
-    console.error(`Failed to process ${event.type}: ${event.id}`, error);
-    throw error; // Rethrow to trigger retry
-  }
+  await handler(event);
+  processedEvents.add(event.id);
+  return true;
 }
 ```
 
-## Idempotency Handling
+### Step 5: Slack Notification Example
 
 ```typescript
-import { Redis } from 'ioredis';
-
-const redis = new Redis(process.env.REDIS_URL);
-
-async function isEventProcessed(eventId: string): Promise<boolean> {
-  const key = `vercel:event:${eventId}`;
-  const exists = await redis.exists(key);
-  return exists === 1;
+// 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 markEventProcessed(eventId: string): Promise<void> {
-  const key = `vercel:event:${eventId}`;
-  await redis.set(key, '1', 'EX', 86400 * 7); // 7 days TTL
+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}`,
+    }),
+  });
 }
 ```
 
-## Webhook Testing
+### Step 6: Test Webhooks Locally
 
 ```bash
-# Use Vercel CLI to send test events
-vercel dev
+# 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
 
-# Or use webhook.site for debugging
-curl -X POST https://webhook.site/your-uuid \
+# Send a test webhook payload
+curl -X POST http://localhost:3000/api/webhooks/vercel \
   -H "Content-Type: application/json" \
-  -d '{"type": "resource.created", "data": {}}'
+  -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"}'
 ```
 
-## Instructions
-
-### Step 1: Register Webhook Endpoint
-Configure your webhook URL in the Vercel dashboard.
+## Webhook Event Types
 
-### Step 2: Implement Signature Verification
-Use the signature verification code to validate incoming webhooks.
-
-### Step 3: Handle Events
-Implement handlers for each event type your application needs.
-
-### Step 4: Add Idempotency
-Prevent duplicate processing with event ID tracking.
+| 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
-- Secure webhook endpoint
-- Signature validation enabled
-- Event handlers implemented
-- Replay attack protection active
-
-## Error Handling
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Invalid signature | Wrong secret | Verify webhook secret |
-| Timestamp rejected | Clock drift | Check server time sync |
-| Duplicate events | Missing idempotency | Implement event ID tracking |
-| Handler timeout | Slow processing | Use async queue |
 
-## Examples
+- Webhook endpoint with HMAC signature verification
+- Event handlers for deployment lifecycle events
+- Idempotent processing preventing duplicates
+- Slack notifications for production deploys and failures
 
-### Testing Webhooks Locally
-```bash
-# Use ngrok to expose local server
-ngrok http 3000
+## Error Handling
 
-# Send test webhook
-curl -X POST https://your-ngrok-url/webhooks/vercel \
-  -H "Content-Type: application/json" \
-  -d '{"type": "test", "data": {}}'
-```
+| 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 |
 
 ## Resources
-- [Vercel Webhooks Guide](https://vercel.com/docs/webhooks)
-- [Webhook Security Best Practices](https://vercel.com/docs/webhooks/security)
+
+- [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`.
+
+For performance optimization, see `vercel-performance-tuning`.

package/skills/vercel-webhooks-events/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Invalid signature | Wrong secret | Verify webhook secret |
+| Timestamp rejected | Clock drift | Check server time sync |
+| Duplicate events | Missing idempotency | Implement event ID tracking |
+| Handler timeout | Slow processing | Use async queue |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-webhooks-events/references/event-handler-pattern.md

@@ -0,0 +1,37 @@
+# Event Handler Pattern
+
+## Event Handler Pattern
+
+```typescript
+type VercelEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';
+
+interface VercelEvent {
+  id: string;
+  type: VercelEventType;
+  data: Record<string, any>;
+  created: string;
+}
+
+const eventHandlers: Record<VercelEventType, (data: any) => Promise<void>> = {
+  'resource.created': async (data) => { /* handle */ },
+  'resource.updated': async (data) => { /* handle */ },
+  'resource.deleted': async (data) => { /* handle */ }
+};
+
+async function handleVercelEvent(event: VercelEvent): Promise<void> {
+  const handler = eventHandlers[event.type];
+
+  if (!handler) {
+    console.log(`Unhandled event type: ${event.type}`);
+    return;
+  }
+
+  try {
+    await handler(event.data);
+    console.log(`Processed ${event.type}: ${event.id}`);
+  } catch (error) {
+    console.error(`Failed to process ${event.type}: ${event.id}`, error);
+    throw error; // Rethrow to trigger retry
+  }
+}
+```

package/skills/vercel-webhooks-events/references/examples.md

@@ -0,0 +1,16 @@
+## Examples
+
+### Testing Webhooks Locally
+
+```bash
+# Use ngrok to expose local server
+ngrok http 3000
+
+# Send test webhook
+curl -X POST https://your-ngrok-url/webhooks/vercel \
+  -H "Content-Type: application/json" \
+  -d '{"type": "test", "data": {}}'
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-webhooks-events/references/signature-verification.md

@@ -0,0 +1,33 @@
+# Signature Verification
+
+## Signature Verification
+
+```typescript
+function verifyVercelSignature(
+  payload: Buffer,
+  signature: string,
+  timestamp: string
+): boolean {
+  const secret = process.env.VERCEL_WEBHOOK_SECRET!;
+
+  // Reject old timestamps (replay attack protection)
+  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
+  if (timestampAge > 300000) { // 5 minutes
+    console.error('Webhook timestamp too old');
+    return false;
+  }
+
+  // Compute expected signature
+  const signedPayload = `${timestamp}.${payload.toString()}`;
+  const expectedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(signedPayload)
+    .digest('hex');
+
+  // Timing-safe comparison
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expectedSignature)
+  );
+}
+```