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

webhook-receiver-hardener — скилл для Claude Code: обзор и установка

Скилл webhook-receiver-hardener помогает проектировать защищённые эндпоинты для вебхуков. Защищает обработчики от подделки запросов, повторных доставок и сбоев сторонних сервисов.

MIT 287 установок ★ 64 обновлён 2026-01-12

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

Что делает webhook-receiver-hardener

Скилл генерирует паттерны и готовые фрагменты кода на TypeScript для надёжного приёма внешних событий. Внутрь входят сверка подписи через HMAC с crypto.timingSafeEqual, защита от повторов на базе Redis с TTL 24 часа и транзакционная запись в базу данных с ограничением unique по идентификатору события.

Код разделяет синхронный ответ и фоновое исполнение. Обработчик мгновенно отдаёт HTTP 200 сервису-отправителю, а саму логику запускает асинхронно. Для ошибок возвращаются строгие статус-коды: 401 при неверной подписи, 400 для битого тела запроса и 500 для повторной попытки провайдером.

Для работы готовых примеров понадобятся Redis и реляционная СУБД с поддержкой транзакций. Без фоновой очереди или Redis приёмник может не выдержать пиковый поток повторов от Stripe или других провайдеров.

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

  • Проверять HMAC-подпись входящих вебхуков без уязвимостей к атакам по времени
  • Исключать повторное выполнение операций при сетевых ретраях провайдера
  • Настроить быстрый ответ HTTP 200 с асинхронной обработкой события
  • Сформировать регламент разбора инцидентов при потере или дублировании запросов

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

  • Защити приёмник вебхуков Stripe с проверкой подписи и дедупликацией через Redis
  • Покажи шаблон эндпоинта для обработки вебхуков с идемпотентной записью в базу
  • Составь план действий для поиска причин дублирования входящих вебхуков

Как установить webhook-receiver-hardener

1Через Skills CLI (Vercel)

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

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

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

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

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

Вопросы о webhook-receiver-hardener

Как установить webhook-receiver-hardener в Claude Code?

Выполните в терминале команду npx skills add patricio0312rev/skills --skill webhook-receiver-hardener -a claude-code. Файл навыка сохранится в каталог ~/.claude/skills/webhook-receiver-hardener/SKILL.md.

Какие задачи решает этот скилл?

Он предоставляет готовые решения для валидации подписей вебхуков, дедупликации через Redis и базу данных, а также правила возврата корректных HTTP-статусов провайдеру.

Какие зависимости нужны для примеров из скилла?

Шаблоны написаны на TypeScript с использованием стандартного модуля Node.js crypto, клиента Redis и конструктора SQL-запросов вроде Knex для транзакций.

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

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

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

Все скиллы по теме «Бэкенд и API» →
sent-webhook-engineer sentdm Скилл sent-webhook-engineer для сборки и отладки приёмников вебхуков Sent v3: проверка подписи, отсев повторов, дедупликация событий и разбор лога доставки. CX Codex +1 2 700установок webhook-engineer VoltAgent Community Субагент webhook-engineer проектирует приём и отправку вебхуков с проверкой HMAC-подписей, дедупликацией событий и защитой от сбоев доставки. CX Codex ★ 26 718звёзд репо webhook-handler-patterns hookdeck Скилл webhook-handler-patterns для Claude Code задаёт архитектуру обработки вебхуков: проверку подписи, парсинг и идемпотентность. Подключается при написании эндпоинтов в Express, Next.js или FastAPI. CX Codex +1 456установок webhook-platform-design Samuel Berthe Скилл webhook-platform-design помогает спроектировать платформу исходящих вебхуков: таксономию событий, подпись HMAC, повторные доставки и журнал отладки. CX Codex +1 10 500установок encore-webhook encoredev Скилл encore-webhook учит агента принимать входящие вебхуки от Stripe, GitHub, Slack и других сервисов через api.raw() и проверять подписи. CX Codex +1 472установок shopify-webhooks hookdeck Скилл shopify-webhooks принимает и проверяет вебхуки Shopify: подпись HMAC-SHA256 в base64, события заказов, товаров и клиентов. Нужен API-секрет приложения. CX Codex +1 291установок

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

Весь набор →
observability-setup Скилл observability-setup разворачивает в проекте трейсы OpenTelemetry, метрики Prometheus и структурные логи, добавляя к ним дашборд Grafana и черновики алертов. CX Codex +1 289установок agent-orchestration-planner Скилл agent-orchestration-planner для проектирования многошаговых агентов: цикл с инструментами, повторные попытки, память и лимит расходов в виде готовых схем на Python. CX Codex +1 288установок react-server-components Помогает проектировать архитектуру React Server Components в Next.js App Router, разделять серверный и клиентский код, настраивать выборку данных и стриминг через Suspense. CX Codex +1 288установок github-actions-pipeline-creator Скилл github-actions-pipeline-creator для Claude Code собирает GitHub Actions workflow для линтинга, тестов, сборки и деплоя. Описывает CI с кэшем, матрицей и артефактами. CX Codex +1 288установок secrets-scanner Скилл secrets-scanner для Claude Code ищет утёкшие ключи, токены и пароли в коде. Ставит проверки до коммита и в CI. CX Codex +1 287установок project-scaffolder Скилл project-scaffolder разворачивает стартовые репозитории под популярные фреймворки с настроенным линтингом, тестовым эндпоинтом и документацией по запуску. CX Codex +1 287установок background-jobs-designer Скилл background-jobs-designer для Claude Code проектирует очереди фоновых задач, повторы и мониторинг. Описывает работу с BullMQ, Celery и асинхронными воркерами. CX Codex +1 286установок adr-writer Скилл adr-writer для Claude Code оформляет архитектурные решения в ADR: фиксирует контекст, выбранный вариант, альтернативы, компромиссы и последствия. Структурирует командные решения. CX Codex +1 286установок

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

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