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
npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a claude-codeWhat 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
statusChangeevents - 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
statusChangeevents forFINISHEDandERRORin 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-code2Manually: put the files in place
~/.claude/skills/cursor-webhooks/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cursor-webhooks/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a codex2Manually: put the files in place
.agents/skills/cursor-webhooks/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a cursor2Manually: put the files in place
.cursor/skills/cursor-webhooks/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills skills/cursor-webhooks2Manually: put the files in place
.github/skills/cursor-webhooks/SKILL.md1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a gemini-cli2Platform CLI
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/cursor-webhooksManually: put the files in place
.devin/skills/cursor-webhooks/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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