# Castle Webhooks

## When to Use This Skill

* How do I receive Castle webhooks?
* How do I verify the `X-Castle-Signature` header?
* Why is my Castle webhook signature verification failing?
* How do I handle `$policy.matched` or `$list_item.created` events?
* Automating suspend/review actions when a Castle policy or list triggers

## Verification (core)

Castle signs the **raw JSON request body** with HMAC-SHA256, keyed with your Castle **API secret** (there is no per-webhook secret), and sends the digest **base64-encoded** in `X-Castle-Signature`. There is no timestamp and no prefix. Verification is optional in Castle's docs but strongly recommended.

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

function verifyCastleSignature(rawBody, signatureHeader, apiSecret) {
  if (!signatureHeader) return false;
  const expected = crypto.createHmac('sha256', apiSecret).update(rawBody).digest('base64');
  try {
    return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
  } catch {
    return false; // different lengths
  }
}

```

Python:

```python
import base64, hashlib, hmac

def verify_castle_signature(raw_body: bytes, signature: str, api_secret: str) -> bool:
    expected = base64.b64encode(
        hmac.new(api_secret.encode(), raw_body, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(signature, expected)

```

The event name is in the JSON body's `type` field (not a header). Respond with any `2xx`; non-2xx responses are retried up to six more times with exponential backoff.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/castle-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/castle-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/castle-webhooks/examples/fastapi/).

## Common Event Types

| `type` | Description |
| --- | --- |
| `$policy.matched` | The conditions of a policy matched (or a policy returned a challenge/deny action) |
| `$list_item.created` | A new item was added to a List (active by default) |
| `$list_item.archived` | A list item was archived (removed from the list) |
| `$list_item.unarchived` | A previously archived list item is active again |

Payload envelope: `api_version`, `app_id`, `created_at`, `type`, `data`. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/castle-webhooks/references/overview.md).

## Environment Variables

```bash
CASTLE_API_SECRET=your_castle_api_secret   # Castle dashboard → Settings → API keys

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/castle-webhooks/references/overview.md) - Castle webhook concepts and events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/castle-webhooks/references/setup.md) - Dashboard configuration
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/castle-webhooks/references/verification.md) - Signature verification details and gotchas