Skip to main content
skill CX Codex

cursor-webhooks — Claude Code skill for receiving webhooks

Set up a handler for Cursor Cloud Agent webhooks, verify request signatures, and respond to agent status changes. Useful when wiring webhook events into an app.

MIT 200 installs ★ 103 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a claude-code
Open on GitHub

What cursor-webhooks does

This skill walks through receiving Cursor Cloud Agent webhooks and checking their signatures. Its Express example uses express.raw() because signature verification needs the untouched request body. A Python example checks signatures with hmac.compare_digest.

The documented event is statusChange; handlers can branch on FINISHED and ERROR, and read the agent summary after completion. Store the signing secret in CURSOR_WEBHOOK_SECRET. For local testing, the skill uses a Hookdeck CLI tunnel started with npx hookdeck-cli listen 3000 cursor --path /webhooks/cursor. It also points to setup notes and framework examples.

What it helps with

  • verify Cursor webhook signatures
  • handle statusChange events
  • respond to agent completion or errors
  • inspect webhook requests through a local Hookdeck tunnel

Example prompts for the agent

  • Set up an Express handler for Cursor Cloud Agent webhooks and verify its signatures.
  • Handle statusChange events for FINISHED and ERROR in my app.
  • Show me how to test a Cursor webhook locally with Hookdeck CLI.

How to install cursor-webhooks

1Skills CLI (Vercel)

npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a claude-code

2Manually: put the files in place

~/.claude/skills/cursor-webhooks/SKILL.md

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

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

Questions about cursor-webhooks

How do I install cursor-webhooks in Claude Code?

Run npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a claude-code. The skill file is placed at ~/.claude/skills/cursor-webhooks/SKILL.md.

What does cursor-webhooks do?

It guides you through receiving Cursor Cloud Agent webhooks, validating signatures, and handling agent status changes.

Why does the Express handler use express.raw()?

Signature checks require the original request body. Parsing it before verification changes the input and causes the check to fail.

Source text

SKILL.md · MIT
---
name: cursor-webhooks
description: >
  Receive and verify Cursor Cloud Agent webhooks. Use when setting up Cursor
  webhook handlers, debugging signature verification, or handling Cloud Agent
  status change events (ERROR, FINISHED).
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# Cursor Webhooks

## When to Use This Skill

- Setting up Cursor Cloud Agent webhook handlers
- Debugging signature verification failures
- Understanding Cursor webhook event types and payloads
- Handling Cloud Agent status change events (ERROR, FINISHED)

## Essential Code (USE THIS)

### Cursor Signature Verification (JavaScript)

```javascript
const crypto = require('crypto');

function verifyCursorWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;

  // Cursor sends: sha256=xxxx
  const [algorithm, signature] = signatureHeader.split('=');
  if (algorithm !== 'sha256') return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false;
  }
}
```

### Express Webhook Handler

```javascript
const express = require('express');
const app = express();

// CRITICAL: Use express.raw() - Cursor requires raw body for signature verification
app.post('/webhooks/cursor',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-webhook-signature'];
    const webhookId = req.headers['x-webhook-id'];
    const event = req.headers['x-webhook-event'];

    // Verify signature
    if (!verifyCursorWebhook(req.body, signature, process.env.CURSOR_WEBHOOK_SECRET)) {
      console.error('Cursor signature verification failed');
      return res.status(401).send('Invalid signature');
    }

    // Parse payload after verification
    const payload = JSON.parse(req.body.toString());

    console.log(`Received ${event} (id: ${webhookId})`);

    // Handle status changes
    if (event === 'statusChange') {
      console.log(`Agent ${payload.id} status: ${payload.status}`);

      if (payload.status === 'FINISHED') {
        console.log(`Summary: ${payload.summary}`);
      } else if (payload.status === 'ERROR') {
        console.error(`Agent error for ${payload.id}`);
      }
    }

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

### Python Signature Verification (FastAPI)

```python
import hmac
import hashlib
from fastapi import Request, HTTPException

def verify_cursor_webhook(body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not secret:
        return False

    # Cursor sends: sha256=xxxx
    parts = signature_header.split('=')
    if len(parts) != 2 or parts[0] != 'sha256':
        return False

    signature = parts[1]
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()

    # Timing-safe comparison
    return hmac.compare_digest(signature, expected)
```

## Common Event Types

| Event Type | Description | Common Use Cases |
|------------|-------------|------------------|
| `statusChange` | Agent status changed | Monitor agent completion, handle errors |

### Event Payload Structure

```json
{
  "event": "statusChange",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "id": "agent_123456",
  "status": "FINISHED",  // or "ERROR"
  "source": {
    "repository": "https://github.com/user/repo",
    "ref": "main"
  },
  "target": {
    "url": "https://github.com/user/repo/pull/123",
    "branchName": "feature-branch",
    "prUrl": "https://github.com/user/repo/pull/123"
  },
  "summary": "Updated 3 files and fixed linting errors"
}
```

## Environment Variables

```bash
# Your Cursor webhook signing secret
CURSOR_WEBHOOK_SECRET=your_webhook_secret_here
```

## Local Development

For local webhook testing, install Hookdeck CLI:

```bash
```

Then start the tunnel:

```bash
npx hookdeck-cli listen 3000 cursor --path /webhooks/cursor
```

No account required. Provides local tunnel + web UI for inspecting requests.

## Resources

- `overview.md` - What Cursor webhooks are, event types
- `setup.md` - Configure webhooks in Cursor dashboard
- `verification.md` - Signature verification details and gotchas
- `examples/` - Runnable examples per framework

## Recommended: webhook-handler-patterns

For production-ready webhook handling, also use the webhook-handler-patterns skill:

- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md)
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md)
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md)
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md)

## Related Skills

- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe webhook handling
- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub webhook handling
- [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify webhook handling
- [openai-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/openai-webhooks) - OpenAI webhook handling
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

© hookdeck · MIT · hookdeck/webhook-skills

Similar skills

All skills for Backend and APIs →

From the same set39

The whole set →
clerk-webhooks This skill guides you through receiving Clerk webhooks and checking their signatures. Use it when building handlers for user, session, or organization events. CX Codex +1 210installs vercel-webhooks Skill for receiving and verifying Vercel webhooks directly in code. Handles webhook setup, signature verification debugging, and reacting to deployment and project events. CX Codex +1 204installs postmark-webhooks Configures handlers for Postmark webhooks. It processes bounces, opens, clicks, spam complaints, and inbound messages. CX Codex +1 203installs openai-webhooks A skill for receiving and verifying OpenAI webhooks. Use it to process fine-tuning events, batch completions, and realtime API callbacks with built-in signature validation. CX Codex +1 202installs deepgram-webhooks A skill for receiving and verifying Deepgram webhooks. Use when you need to handle asynchronous transcription results or build a callback handler for completed transcription requests. CX Codex +1 200installs gitlab-webhooks Skill for handling GitLab webhooks with signature and token verification. Use it to set up webhook handlers for push, merge request, and pipeline events, or debug authentication failures. CX Codex +1 199installs hookdeck-event-gateway-webhooks Verifies webhook signatures from Hookdeck Event Gateway. Webhooks arrive with an x-hookdeck-signature header — the skill provides ready-to-use functions for HMAC SHA-256 validation. CX Codex +1 198installs replicate-webhooks Receive and verify Replicate webhooks across Express or FastAPI. Handles model prediction lifecycle events and HMAC signature verification. CX Codex +1 198installs

Project sponsors

Companies that keep this analytics open