Shortcut Webhooks Skill

When to Use This Skill

• How do I receive Shortcut (Clubhouse) webhooks?
• How do I verify the Shortcut Payload-Signature header?
• Why is my Shortcut webhook signature verification failing?
• How do I handle story create, story update or epic update events?
• Why are my Shortcut webhooks arriving without a signature?

Verification (core)

Shortcut signs a webhook only if you entered a secret when creating it. The Payload-Signature header is the hex-encoded HMAC-SHA256 of the raw request body (UTF-8), keyed with that secret string. There is no timestamp and no prefix. Shortcut has no webhook verification SDK, so verify manually and compare timing-safe.

Node:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signatureHeader.trim().toLowerCase()), Buffer.from(expected));
  } catch {
    return false; // different lengths
  }
}

Python:

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not secret:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header.strip().lower().encode(), expected.encode())

In Express, read the body with express.raw({ type: '*/*' }) so any content type is verified against the exact bytes received.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Payload and Event Dispatch

Each delivery is one JSON event: { id, changed_at, primary_id?, member_id, version, actions: [...], references: [...] }. Shortcut has no event-type header. Dispatch on each item in actions[] by entity_type and action; one delivery can hold several actions.

Shortcut fires for story and epic create, update and delete, including their comments and tasks. See references/overview.md for details.

Environment Variables

SHORTCUT_WEBHOOK_SECRET=your_webhook_secret   # The secret you entered when creating the webhook

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 shortcut --path /webhooks/shortcut

Reference Materials

• references/overview.md - Shortcut webhook concepts, payload structure, events
• references/setup.md - Creating the webhook and setting a secret
• references/verification.md - Signature verification details and gotchas