К основному содержанию
скилл CX Codex

cursor-webhooks — скилл для Claude Code: приём вебхуков

Скилл cursor-webhooks помогает настроить приём вебхуков Cursor Cloud Agent, проверить подпись и обработать смену статуса. Пригодится при подключении обработчика к проекту.

MIT 200 установок ★ 103 обновлён 2026-10-22

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a claude-code
Открыть на GitHub

Что делает cursor-webhooks

Скилл показывает, как принимать вебхуки Cursor Cloud Agent и проверять подпись запроса. В примере для Express используется express.raw(): если разобрать тело запроса до проверки подписи, проверка не сработает. Для Python приведена проверка через hmac.compare_digest.

Основное событие — statusChange: обработчик может реагировать на статусы FINISHED и ERROR, а при завершении читать сводку агента. Секрет подписи задаётся через CURSOR_WEBHOOK_SECRET. Для локального тестирования описан туннель Hookdeck CLI командой npx hookdeck-cli listen 3000 cursor --path /webhooks/cursor; также есть материалы по настройке в Cursor и примеры для разных фреймворков.

Какие задачи решает

  • проверить подпись вебхука Cursor
  • обработать событие statusChange
  • реагировать на завершение или ошибку агента
  • проверить запросы через локальный туннель Hookdeck

Примеры запросов агенту

  • Настрой обработчик вебхуков Cursor Cloud Agent на Express и проверь подпись.
  • Добавь обработку statusChange для статусов FINISHED и ERROR.
  • Помоги проверить вебхук Cursor локально через Hookdeck CLI.

Как установить cursor-webhooks

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/cursor-webhooks/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о cursor-webhooks

Как установить cursor-webhooks в Claude Code?

Выполни npx skills add hookdeck/webhook-skills --skill cursor-webhooks -a claude-code. Файл скилла появится по пути ~/.claude/skills/cursor-webhooks/SKILL.md.

Что делает cursor-webhooks?

Помогает принимать вебхуки Cursor Cloud Agent, проверять подписи и обрабатывать смену статуса агента.

Почему для Express нужен express.raw()?

Проверка подписи использует исходное тело запроса. Если Express заранее преобразует его в объект, верификация не пройдёт.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
documenso-webhooks-events Jeremy Longshore Скилл documenso-webhooks-events помогает настроить приём вебхуков сервиса Documenso. Пригодится при отслеживании подписания документов и передаче статусов во внешние сервисы. CX Codex +1 1установок setup-zoom-webhooks официальный anthropics Скилл setup-zoom-webhooks для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI с эталонной документацией по Zoom webhooks. Включается при реализации подписок на события, проверки подписи x-zm-signature и обработки доставки. CX Codex +1 2 200установок maintainx-webhooks-events Jeremy Longshore Скилл maintainx-webhooks-events настраивает приём вебхуков MaintainX и обработку событий рабочих заказов в Express. Помогает связать обновления ТОиР с внешними сервисами. CX Codex +1 1установок MCP Events bridge hookdeck MCP-сервер MCP Events bridge для Claude Code превращает вебхуки в события, на которые подписываются ИИ-агенты через Hookdeck Event Gateway. CX Codex +1 ★ 9звёзд репо clerk-webhooks clerk Скилл clerk-webhooks для Claude Code помогает создавать обработчики вебхуков Clerk с проверкой подписи. Запускается при настройке синхронизации данных и действий на событиях Clerk. CX Codex +1 55 700установок sumsub-manage-webhooks sumsub Скилл sumsub-manage-webhooks управляет подписками на вебхуки Sumsub в песочнице. Скилл читает, создаёт и меняет адреса приёма событий верификации через скрипты автоматизации. CX Codex +1 1 400установок

Из того же набора39

Весь набор →
clerk-webhooks Скилл clerk-webhooks помогает написать обработчик вебхуков Clerk и проверить подпись запроса. Пригодится при настройке событий пользователей, сессий и организаций. CX Codex +1 210установок vercel-webhooks Скилл vercel-webhooks для приёма и проверки вебхуков Vercel прямо в коде. Помогает при настройке обработчиков, отладке проверки подписей и реагировании на события развёртывания и проектов. CX Codex +1 204установок postmark-webhooks Скилл postmark-webhooks для Claude Code помогает принимать и обрабатывать вебхуки Postmark. Настраивает обработку доставок, кликов, открытий, жалоб на спам и входящих сообщений. CX Codex +1 203установок openai-webhooks Скилл openai-webhooks для Claude Code принимает и проверяет вебхуки OpenAI. Обрабатывает события fine-tuning, batch API и realtime API с проверкой подписей. CX Codex +1 202установок deepgram-webhooks Скилл deepgram-webhooks для Claude Code принимает и проверяет вебхуки Deepgram. Обрабатывает асинхронные результаты транскрипции и колбэки завершённых запросов. CX Codex +1 200установок gitlab-webhooks Скилл gitlab-webhooks для Claude Code обрабатывает вебхуки GitLab с проверкой подписей и токенов. Помогает отлаживать верификацию вебхуков для push-событий, merge-request и pipeline. CX Codex +1 199установок hookdeck-event-gateway-webhooks Скилл hookdeck-event-gateway-webhooks проверяет подпись вебхуков, которые прошли через Hookdeck Event Gateway. Вебхук приходит с заголовком x-hookdeck-signature — скилл даёт готовые функции для проверки HMAC SHA-256. CX Codex +1 198установок replicate-webhooks Скилл replicate-webhooks для Claude Code принимает и проверяет вебхуки Replicate в Express или FastAPI, обрабатывает статусы предсказаний и проверяет HMAC-подпись. CX Codex +1 198установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой