Skip to main content
skill CX Codex

webhook-receiver-hardener — Claude Code skill: setup and features

webhook-receiver-hardener hardens webhook endpoints against spoofing, replay attacks, and duplicate event deliveries. Generates verification code, dedupe strategies, and incident guides.

MIT 287 installs ★ 64 updated 2026-01-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill webhook-receiver-hardener -a claude-code
Open on GitHub

What webhook-receiver-hardener does

This skill provides production-grade TypeScript recipes for building resilient event endpoints. It covers HMAC validation via crypto.timingSafeEqual, a 24-hour Redis deduplication layer, and database writes using a unique constraint on the event identifier.

The logic separates acknowledgement from execution. The handler returns an immediate HTTP 200 response to satisfy provider timeouts, then processes the payload asynchronously. Status codes match provider retry contracts: 401 halts bad signatures, 400 stops malformed requests, and 500 triggers provider retries.

Applying these patterns directly requires Redis and a transactional SQL database. Without a shared cache or atomic storage, multiple concurrent deliveries will cause race conditions.

What it helps with

  • Validate webhook HMAC signatures without timing attack risks
  • Prevent duplicate execution on provider retries using Redis and SQL constraints
  • Acknowledge incoming events immediately while processing payloads asynchronously
  • Debug delivery failures and missing payloads using structured incident runbooks

Example prompts for the agent

  • Harden our Stripe webhook endpoint with signature verification and Redis dedupe
  • Show me an idempotent webhook handler using Express and SQL transactions
  • Draft an incident checklist for investigating high error rates on incoming webhooks

How to install webhook-receiver-hardener

1Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill webhook-receiver-hardener -a claude-code

2Manually: put the files in place

~/.claude/skills/webhook-receiver-hardener/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/webhook-receiver-hardener/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about webhook-receiver-hardener

How to install webhook-receiver-hardener in Claude Code?

Run npx skills add patricio0312rev/skills --skill webhook-receiver-hardener -a claude-code in your terminal. The file is saved to ~/.claude/skills/webhook-receiver-hardener/SKILL.md.

What does webhook-receiver-hardener do?

It gives the agent instructions and patterns to implement HMAC verification, idempotency logic, immediate 200 acknowledgements, and retry handling for external webhooks.

What storage does the idempotency strategy expect?

The reference code relies on Redis for fast deduplication checks and a relational database table with an index constraint for persistent idempotency.

Source text

SKILL.md · MIT
---
name: webhook-receiver-hardener
description: Secures webhook receivers with signature verification, retry handling, deduplication, idempotency keys, and error responses. Provides verification code, dedupe storage strategy, runbook for incidents. Use when implementing "webhooks", "webhook security", "event receivers", or "third-party integrations".
---

# Webhook Receiver Hardener

Build secure, reliable webhook endpoints that handle failures gracefully.

## Core Security

**Signature Verification**: HMAC validation before processing
**Deduplication**: Track processed webhook IDs
**Idempotency**: Safe to process same webhook multiple times
**Retries**: Handle provider retry attempts
**Rate Limiting**: Prevent abuse

## Signature Verification

```typescript
import crypto from "crypto";

export const verifyWebhookSignature = (
  payload: string,
  signature: string,
  secret: string
): boolean => {
  const hmac = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(hmac));
};

// Stripe example
router.post(
  "/webhooks/stripe",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const sig = req.headers["stripe-signature"];

    try {
      const event = stripe.webhooks.constructEvent(
        req.body,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET
      );
      await processStripeEvent(event);
      res.json({ received: true });
    } catch (err) {
      return res.status(400).send(`Webhook Error: ${err.message}`);
    }
  }
);
```

## Deduplication

```typescript
// Redis-based dedupe
const WEBHOOK_TTL = 60 * 60 * 24; // 24 hours

export const isDuplicate = async (webhookId: string): Promise<boolean> => {
  const key = `webhook:${webhookId}`;
  const exists = await redis.exists(key);

  if (exists) return true;

  await redis.setex(key, WEBHOOK_TTL, "1");
  return false;
};

// Usage
if (await isDuplicate(webhook.id)) {
  return res.status(200).json({ received: true }); // Already processed
}
```

## Idempotent Processing

```typescript
export const processWebhook = async (webhook: Webhook) => {
  // Use database transaction with unique constraint
  try {
    await db.transaction(async (trx) => {
      // Insert webhook record (unique constraint on webhook_id)
      await trx("processed_webhooks").insert({
        webhook_id: webhook.id,
        processed_at: new Date(),
      });

      // Do actual processing
      await performWebhookAction(webhook, trx);
    });
  } catch (err) {
    if (err.code === "23505") {
      // Unique violation
      console.log("Webhook already processed");
      return; // Idempotent - already processed
    }
    throw err;
  }
};
```

## Retry Handling

```typescript
// Acknowledge immediately, process async
router.post("/webhooks/provider", async (req, res) => {
  // Verify signature
  if (!verifySignature(req.body, req.headers["signature"])) {
    return res.status(401).send("Invalid signature");
  }

  // Return 200 immediately
  res.status(200).json({ received: true });

  // Process async
  processWebhookAsync(req.body).catch((err) => {
    console.error("Webhook processing failed:", err);
    // Will be retried by provider
  });
});

// Exponential backoff for provider retries
// Attempt 1: immediate
// Attempt 2: +5 minutes
// Attempt 3: +15 minutes
// Attempt 4: +1 hour
// Attempt 5: +6 hours
```

## Error Responses

```typescript
// Return appropriate status codes
const webhookHandler = async (req, res) => {
  // 400: Malformed payload (won't retry)
  if (!isValidPayload(req.body)) {
    return res.status(400).json({ error: "Invalid payload" });
  }

  // 401: Invalid signature (won't retry)
  if (!verifySignature(req.body, req.headers["signature"])) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // 200: Already processed (idempotent)
  if (await isDuplicate(req.body.id)) {
    return res.status(200).json({ received: true });
  }

  // 500: Processing error (will retry)
  try {
    await processWebhook(req.body);
    return res.status(200).json({ received: true });
  } catch (err) {
    console.error("Processing error:", err);
    return res.status(500).json({ error: "Processing failed" });
  }
};
```

## Monitoring & Runbook

```markdown
## Webhook Incidents

### High Error Rate

1. Check provider status page
2. Review recent code deploys
3. Check signature secret rotation
4. Verify database connectivity

### Missing Webhooks

1. Check provider sending (their dashboard)
2. Verify endpoint is accessible
3. Check rate limiting rules
4. Review dedupe cache TTL

### Duplicate Processing

1. Check dedupe cache connectivity
2. Verify unique constraints
3. Review idempotency logic
```

## Best Practices

- Verify signature BEFORE any processing
- Return 200 quickly, process async
- Dedupe with Redis + database constraints
- Log all webhook attempts
- Monitor processing latency
- Set up alerts for failures
- Document expected payload schemas

## Output Checklist

- [ ] Signature verification
- [ ] Deduplication mechanism
- [ ] Idempotent processing
- [ ] Async processing pattern
- [ ] Proper status codes
- [ ] Error logging
- [ ] Monitoring/alerts
- [ ] Incident runbook

© patricio0312rev · MIT · patricio0312rev/skills

Similar skills

All skills for Backend and APIs →

From the same set148

The whole set →
observability-setup observability-setup brings OpenTelemetry tracing, Prometheus metrics and structured logging into one setup, with a Grafana dashboard and starter alert rules attached. CX Codex +1 289installs agent-orchestration-planner agent-orchestration-planner — a skill that lays out a multi-step agent: tool loop, retries, memory and a spending cap, with Python snippets you can lift into a project. CX Codex +1 288installs react-server-components Guides component architecture in Next.js App Router with React Server Components, server-side data fetching, Suspense streaming, and boundary setup. CX Codex +1 288installs github-actions-pipeline-creator github-actions-pipeline-creator builds GitHub Actions workflows for linting, tests, builds, and deployment. Useful when a project needs caching, matrix runs, artifacts, or failure reports. CX Codex +1 288installs secrets-scanner secrets-scanner catches leaked keys, tokens and passwords in a repo, with checks before commit and in CI. Handy when a .env file or a live key already slipped into history. CX Codex +1 287installs project-scaffolder project-scaffolder scaffolds complete starter repositories for web and API frameworks with configs, tooling, working baseline routes, and setup guides. CX Codex +1 287installs background-jobs-designer The background-jobs-designer skill designs queued background work with retries, idempotency, and monitoring. Use it when building BullMQ, Celery, or worker-based processing. CX Codex +1 286installs adr-writer The adr-writer skill turns technical choices into Architecture Decision Records with context, options, tradeoffs, consequences, and owners. Use it when a decision needs a lasting record. CX Codex +1 286installs

Project sponsors

Companies that keep this analytics open