cursor-webhooks

Validate Cursor Cloud Agent webhook signatures with HMAC-SHA256.

79|11|Updated Jan 30, 2026
One-click install
npx skills add https://github.com/hookdeck/webhook-skills --skill cursor-webhooks
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: cursor-webhooks
Source: https://github.com/hookdeck/webhook-skills/tree/main/skills/cursor-webhooks
Command: npx skills add https://github.com/hookdeck/webhook-skills --skill cursor-webhooks

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Cursor webhooks provide a way for your app to receive real-time agent status changes from Cursor Cloud Agent and verify that callbacks are authentic, preventing spoofed requests and data leakage.

Core Features & Use Cases

  • Signature verification: Validate the X-Webhook-Signature header using HMAC-SHA256 with your secret.
  • Event handling: Process statusChange events (FINISHED, ERROR) and access payload data like id, timestamp, source, and target.
  • Framework support: Works with Express, Next.js, and FastAPI samples for rapid local testing and integration.
  • Local testing: Use Hookdeck CLI tunnels or local dev servers to simulate Cursor webhooks during development.

Quick Start

Set up a Cursor webhook endpoint and verify signatures using the sample payloads in the examples folder.

Frequently Asked Questions about cursor-webhooks

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I verify Cursor Cloud Agent webhook signatures?

To verify Cursor Cloud Agent webhook signatures, validate the X-Webhook-Signature header using HMAC-SHA256 with your CURSOR_WEBHOOK_SECRET against the raw request body. This ensures authentic event delivery and prevents spoofed requests.

Can I process Cursor webhook statusChange events in Next.js and Express?

Yes, you can process Cursor webhook statusChange events in Next.js and Express. The Skill provides framework-specific samples to handle FINISHED and ERROR events, allowing you to access payload data like id, timestamp, source, and target.

Do I need a raw request body for Cursor webhook signature validation?

Yes, you need the raw request body for Cursor webhook signature validation. Using the parsed or modified body will cause the HMAC-SHA256 signature verification to fail, so you must access the unaltered raw stream to compute the hash.

What is the best way to test Cursor webhooks locally during development?

The best way to test Cursor webhooks locally is by using Hookdeck CLI tunnels or local dev servers. This simulates real statusChange events, allowing you to debug your signature verification and event handling logic before deploying.

What environment variables are required to receive Cursor webhooks?

You must configure the CURSOR_WEBHOOK_SECRET environment variable to receive and verify Cursor webhooks. This secret is essential for computing the HMAC-SHA256 hash to validate the X-Webhook-Signature header on incoming statusChange events.