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

chargebee-webhooks — скилл для Claude Code

Скилл chargebee-webhooks настраивает приём и проверку вебхуков Chargebee через Basic Auth. Помогает обрабатывать события биллинга подписок в Express, Next.js и FastAPI.

MIT 195 установок ★ 103 обновлён 2026-10-22

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

Что делает chargebee-webhooks

Скилл даёт готовые шаблоны эндпоинтов для обработки вебхуков биллинга Chargebee. В отличие от сервисов с HMAC-подписями, Chargebee использует обычную Basic-аутентификацию. Поэтому сервису не нужен доступ к исходному телу запроса: фреймворки вроде Express могут сразу парсить входящие данные через express.json().

Внутри собраны примеры интеграции для трёх окружений: Express.js, Next.js с App Router и FastAPI. Логика разбирает заголовок Authorization, сверяет связку логина и пароля и распределяет события по типам: оформление подписки, отмена или успешное списание.

Для работы обработчиков обязательно настроить переменные окружения CHARGEBEE_WEBHOOK_USERNAME и CHARGEBEE_WEBHOOK_PASSWORD. Без них проверка авторизации вернёт ошибку 401. Также перед запуском необходимо сверить точные названия событий в личном кабинете Chargebee, поскольку имена меняются между версиями API.

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

  • проверить Basic Auth в заголовках вебхуков Chargebee
  • настроить обработчик событий подписок и платежей для FastAPI
  • обработать вебхуки биллинга в роутах Next.js App Router
  • отладить приём локальных вебхуков через Hookdeck CLI

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

  • Сделай роут для вебхуков Chargebee в Next.js App Router с проверкой Basic Auth
  • Напиши обработчик событий subscription_cancelled и payment_failed на Express
  • Добавь верификацию заголовка Authorization из вебхуков Chargebee в FastAPI

Как установить chargebee-webhooks

1Через Skills CLI (Vercel)

npx skills add hookdeck/webhook-skills --skill chargebee-webhooks -a claude-code

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

~/.claude/skills/chargebee-webhooks/SKILL.md

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

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

Вопросы о chargebee-webhooks

Как установить chargebee-webhooks в Claude Code?

Выполните команду npx skills add hookdeck/webhook-skills --skill chargebee-webhooks -a claude-code. Навык будет добавлен в проект, а его манифест запишется в ~/.claude/skills/chargebee-webhooks/SKILL.md.

Что делает chargebee-webhooks?

Генерирует готовые функции верификации Basic Auth и структуры роутов для приёма биллинговых уведомлений Chargebee. Включает типовые сценарии обработки подписок и счетов для Node.js и Python.

Нужна ли проверка HMAC для вебхуков Chargebee?

Нет, Chargebee применяет HTTP Basic Auth вместо HMAC-подписей. Сырое тело запроса для валидации не требуется, поэтому можно применять стандартный JSON-парсер.

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

SKILL.md · MIT
---
name: chargebee-webhooks
description: >
  Receive and verify Chargebee webhooks. Use when setting up Chargebee webhook
  handlers, debugging Basic Auth verification, or handling subscription billing events.
license: MIT
metadata:
  author: hookdeck
  version: "0.1.0"
  repository: https://github.com/hookdeck/webhook-skills
---

# Chargebee Webhooks

## When to Use This Skill

- Setting up Chargebee webhook handlers
- Debugging Basic Auth verification failures
- Understanding Chargebee event types and payloads
- Processing subscription billing events

## Essential Code

Chargebee uses Basic Authentication for webhook verification. Here's how to implement it:

### Express.js

```javascript
// Verify Chargebee webhook with Basic Auth
// NOTE: Chargebee uses Basic Auth (not HMAC signatures), so raw body access
// is not required. Use express.json() for automatic JSON parsing:
app.post('/webhooks/chargebee', express.json(), (req, res) => {
  // Extract Basic Auth credentials
  const auth = req.headers.authorization;
  if (!auth || !auth.startsWith('Basic ')) {
    return res.status(401).send('Unauthorized');
  }

  // Decode and verify credentials
  const encoded = auth.substring(6);
  const decoded = Buffer.from(encoded, 'base64').toString('utf-8');
  const [username, password] = decoded.split(':');

  const expectedUsername = process.env.CHARGEBEE_WEBHOOK_USERNAME;
  const expectedPassword = process.env.CHARGEBEE_WEBHOOK_PASSWORD;

  if (username !== expectedUsername || password !== expectedPassword) {
    return res.status(401).send('Invalid credentials');
  }

  // Access the parsed JSON directly
  const event = req.body;
  console.log(`Received ${event.event_type} event:`, event.id);

  // Handle specific event types
  switch (event.event_type) {
    case 'subscription_created':
    case 'subscription_changed':
    case 'subscription_cancelled':
      // Process subscription events
      break;
    case 'payment_succeeded':
    case 'payment_failed':
      // Process payment events
      break;
  }

  res.status(200).send('OK');
});

// Note: If you later need raw body access (e.g., for HMAC signature
// verification with other providers), use express.raw():
// app.post('/webhooks/other', express.raw({ type: 'application/json' }), (req, res) => {
//   const rawBody = req.body.toString();
//   // ... verify signature using rawBody ...
// });
```

### Next.js (App Router)

```typescript
// app/webhooks/chargebee/route.ts
import { NextRequest } from 'next/server';

export async function POST(req: NextRequest) {
  // Extract Basic Auth credentials
  const auth = req.headers.get('authorization');
  if (!auth || !auth.startsWith('Basic ')) {
    return new Response('Unauthorized', { status: 401 });
  }

  // Decode and verify credentials
  const encoded = auth.substring(6);
  const decoded = Buffer.from(encoded, 'base64').toString('utf-8');
  const [username, password] = decoded.split(':');

  const expectedUsername = process.env.CHARGEBEE_WEBHOOK_USERNAME;
  const expectedPassword = process.env.CHARGEBEE_WEBHOOK_PASSWORD;

  if (username !== expectedUsername || password !== expectedPassword) {
    return new Response('Invalid credentials', { status: 401 });
  }

  // Process the webhook
  const event = await req.json();
  console.log(`Received ${event.event_type} event:`, event.id);

  return new Response('OK', { status: 200 });
}
```

### FastAPI

```python
# main.py
from fastapi import FastAPI, Header, HTTPException, Depends
from typing import Optional
import base64
import os

app = FastAPI()

def verify_chargebee_auth(authorization: Optional[str] = Header(None)):
    """Verify Chargebee webhook Basic Auth"""
    if not authorization or not authorization.startswith("Basic "):
        raise HTTPException(status_code=401, detail="Unauthorized")

    # Decode credentials
    encoded = authorization[6:]
    decoded = base64.b64decode(encoded).decode('utf-8')

    # Split username:password (handle colons in password)
    if ':' not in decoded:
        raise HTTPException(status_code=401, detail="Invalid authorization format")

    colon_index = decoded.index(':')
    username = decoded[:colon_index]
    password = decoded[colon_index + 1:]

    expected_username = os.getenv("CHARGEBEE_WEBHOOK_USERNAME")
    expected_password = os.getenv("CHARGEBEE_WEBHOOK_PASSWORD")

    if username != expected_username or password != expected_password:
        raise HTTPException(status_code=401, detail="Invalid credentials")

    return True

@app.post("/webhooks/chargebee")
async def handle_chargebee_webhook(
    event: dict,
    auth_valid: bool = Depends(verify_chargebee_auth)
):
    """Handle Chargebee webhook events"""
    event_type = event.get("event_type")
    print(f"Received {event_type} event: {event.get('id')}")

    # Process event based on type
    if event_type in ["subscription_created", "subscription_changed", "subscription_cancelled"]:
        # Handle subscription events
        pass
    elif event_type in ["payment_succeeded", "payment_failed"]:
        # Handle payment events
        pass

    return {"status": "OK"}
```

## Common Event Types

> **⚠️ WARNING: Verify Event Names!**
>
> The event type names below are examples and **MUST be verified** against the [Chargebee API documentation](https://apidocs.chargebee.com/docs/api/events#event_types) for your specific Chargebee configuration. Event names can vary significantly between API versions and configurations.
>
> **Special attention required for:**
> - Payment events (shown as `payment_succeeded` and `payment_failed` below)
> - Invoice events (shown as `invoice_generated` below)
> - Any custom events specific to your Chargebee setup
>
> **Always check your Chargebee Webhook settings for the exact event names your account uses.**

| Event | Triggered When | Common Use Cases |
|-------|----------------|------------------|
| `subscription_created` | New subscription is created | Provision access, send welcome email |
| `subscription_changed` | Subscription is modified | Update user permissions, sync changes |
| `subscription_cancelled` | Subscription is cancelled | Revoke access, trigger retention flow |
| `subscription_reactivated` | Cancelled subscription is reactivated | Restore access, send notification |
| `payment_succeeded` | Payment is successfully processed | Update payment status, send receipt |
| `payment_failed` | Payment attempt fails | Retry payment, notify customer |
| `invoice_generated` | Invoice is created | Send invoice to customer |
| `customer_created` | New customer is created | Create user account, sync data |

## Environment Variables

```bash
# Chargebee webhook Basic Auth credentials
CHARGEBEE_WEBHOOK_USERNAME=your_webhook_username
CHARGEBEE_WEBHOOK_PASSWORD=your_webhook_password
```

## Local Development

For local webhook testing, use Hookdeck CLI:

```bash
npx hookdeck-cli listen 3000 chargebee --path /webhooks/chargebee
```

No account required. Provides local tunnel + web UI for inspecting requests.

## Reference Materials

- [Overview](references/overview.md) - What Chargebee webhooks are, common event types
- [Setup](references/setup.md) - Configure webhooks in Chargebee dashboard
- [Verification](references/verification.md) - Basic Auth verification details and gotchas

## Examples

- [Express Example](examples/express/) - Complete Express.js implementation with tests
- [Next.js Example](examples/nextjs/) - Next.js App Router implementation with tests
- [FastAPI Example](examples/fastapi/) - Python FastAPI implementation with tests

## Recommended: webhook-handler-patterns

We recommend installing the [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):

- [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md) — Verify first, parse second, handle idempotently third
- [Idempotency](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/idempotency.md) — Prevent duplicate processing
- [Error handling](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/error-handling.md) — Return codes, logging, dead letter queues
- [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md) — Provider retry schedules, backoff patterns

## Related Skills

- [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe payment webhook handling
- [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify e-commerce webhook handling
- [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository webhook handling
- [resend-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/resend-webhooks) - Resend email webhook handling
- [clerk-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/clerk-webhooks) - Clerk auth webhook handling
- [elevenlabs-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/elevenlabs-webhooks) - ElevenLabs webhook handling
- [openai-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/openai-webhooks) - OpenAI webhook handling
- [paddle-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/paddle-webhooks) - Paddle billing webhook handling
- [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Handler sequence, idempotency, error handling, retry logic
- [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

© hookdeck · MIT · hookdeck/webhook-skills

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

Все скиллы по теме «Бэкенд и API» →
mcp-chargebee codespar Управляет биллингом, подписками и счетами в Chargebee прямо из чата с ИИ-ассистентом. Пригодится разработчикам SaaS для автоматизации операций с клиентами. CX Codex +1 ★ 279звёзд репо setup-zoom-webhooks официальный anthropics Скилл setup-zoom-webhooks для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI с эталонной документацией по Zoom webhooks. Включается при реализации подписок на события, проверки подписи x-zm-signature и обработки доставки. CX Codex +1 2 200установок framework-adapters dodopayments Скилл framework-adapters подключает официальные адаптеры Dodo Payments в Next.js, Express, Hono или Nuxt. Настраивает маршруты для чекаута, портала клиента и вебхуков. CX Codex +1 209установок maintainx-webhooks-events Jeremy Longshore Скилл maintainx-webhooks-events настраивает приём вебхуков MaintainX и обработку событий рабочих заказов в Express. Помогает связать обновления ТОиР с внешними сервисами. CX Codex +1 1установок documenso-webhooks-events Jeremy Longshore Скилл documenso-webhooks-events помогает настроить приём вебхуков сервиса Documenso. Пригодится при отслеживании подписания документов и передаче статусов во внешние сервисы. CX Codex +1 1установок clerk-webhooks clerk Скилл clerk-webhooks для Claude Code помогает создавать обработчики вебхуков Clerk с проверкой подписи. Запускается при настройке синхронизации данных и действий на событиях Clerk. CX Codex +1 55 700установок

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

Весь набор →
hookdeck-event-gateway-webhooks Скилл hookdeck-event-gateway-webhooks проверяет подпись вебхуков, которые прошли через Hookdeck Event Gateway. Вебхук приходит с заголовком x-hookdeck-signature — скилл даёт готовые функции для проверки HMAC SHA-256. CX Codex +1 198установок replicate-webhooks Скилл replicate-webhooks для Claude Code принимает и проверяет вебхуки Replicate в Express или FastAPI, обрабатывает статусы предсказаний и проверяет HMAC-подпись. CX Codex +1 198установок outpost Скилл outpost помогает спроектировать доставку событий из SaaS или API-платформы в HTTP, SQS, RabbitMQ и другие назначения. CX Codex +1 196установок fusionauth-webhooks Скилл fusionauth-webhooks учит агента принимать вебхуки FusionAuth и сверять JWT-подписи. Помогает настроить валидацию событий авторизации и пользователей в Express или FastAPI. CX Codex +1 196установок webflow-webhooks Скилл webflow-webhooks помогает принимать события Webflow, проверять подписи и разбирать ошибки обработчиков. Нужен при настройке форм, заказов и CMS-вебхуков. CX Codex +1 190установок paypal-webhooks Скилл paypal-webhooks для Claude Code принимает и проверяет вебхуки PayPal с подписью RSA-SHA256. Обрабатывает события платежей, подписок и возвратов. CX Codex +1 133установок discord-webhooks Скилл discord-webhooks для Claude Code настраивает приём и проверку исходящих вебхуков Discord. Обрабатывает события и помогает отлаживать ошибки подписи. CX Codex +1 131установок slack-webhooks Скилл slack-webhooks помогает настроить приём вебхуков Slack Events API, пройти проверку url_verification и настроить валидацию подписи запросов. CX Codex +1 128установок

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

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