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

maintainx-webhooks-events — скилл для Claude Code

Скилл maintainx-webhooks-events настраивает приём вебхуков MaintainX и обработку событий рабочих заказов в Express. Помогает связать обновления ТОиР с внешними сервисами.

MIT 1 установок ★ 2 935 обновлён 2026-10-29

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

Что делает maintainx-webhooks-events

Скилл содержит инструкции и примеры кода для сервера Express на TypeScript. Он настраивает проверку цифровой подписи HMAC SHA-256 в заголовке x-maintainx-signature через безопасное сравнение байтов, а также маршрутизирует события жизненного цикла рабочих заказов.

Внутрь заложена защита от повторных уведомлений: обработчик сверяет идентификатор из заголовка x-maintainx-event-id перед выполнением логики. Для управления подписками используются вызовы REST API MaintainX через curl.

Перед запуском обязательно задать переменную окружения MAINTAINX_API_KEY и получить доступ к API MaintainX. Без публичного HTTPS-эндпоинта сервис не сможет доставить вебхуки на локальную машину, поэтому для разработки потребуется туннель вроде ngrok.

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

  • Проверять цифровую подпись HMAC SHA-256 во входящих запросах MaintainX
  • Отсекать повторные события по заголовку x-maintainx-event-id
  • Регистрировать подписки на события рабочих заказов через REST API
  • Маршрутизировать статусы заявок на обслуживание в сторонние системы

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

  • Настрой приём вебхуков MaintainX на Express с проверкой подписи
  • Зарегистрируй вебхук MaintainX для событий workorder.created и workorder.completed
  • Добавь дедупликацию событий MaintainX по event-id

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

1Через Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill maintainx-webhooks-events -a claude-code

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

~/.claude/skills/maintainx-webhooks-events/SKILL.md

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

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

Вопросы о maintainx-webhooks-events

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

Выполните команду npx skills add jeremylongshore/tons-of-skills-marketplace --skill maintainx-webhooks-events -a claude-code.

Что делает maintainx-webhooks-events?

Он даёт агенту шаблоны для Express: проверку подписи HMAC SHA-256, дедупликацию запросов через идемпотентность и роутинг событий рабочих заказов MaintainX.

Что требуется подготовить перед настройкой?

Понадобятся аккаунт MaintainX с доступом к API, ключ в переменной MAINTAINX_API_KEY и публичный HTTPS-адрес, доступный из интернета.

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

SKILL.md · MIT
---
name: maintainx-webhooks-events
description: 'Implement MaintainX webhook handling and event-driven integrations.

  Use when setting up webhooks, handling MaintainX events,

  or building real-time integrations with MaintainX.

  Trigger with phrases like "maintainx webhook", "maintainx events",

  "maintainx notifications", "maintainx real-time", "maintainx triggers".

  '
allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(npm:*)
version: 1.11.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- maintainx
- webhooks
compatibility: Designed for Claude Code
---
# MaintainX Webhooks & Events

## Overview

Build real-time integrations with MaintainX using webhooks for work order updates, asset changes, and maintenance notifications. MaintainX fires webhook events when key resources change.

## Prerequisites

- MaintainX account with API access
- HTTPS endpoint accessible from the internet (ngrok for local dev)
- `MAINTAINX_API_KEY` environment variable configured

## Instructions

### Step 1: Register a Webhook

```bash
curl -X POST https://api.getmaintainx.com/v1/webhooks \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/maintainx",
    "events": [
      "workorder.created",
      "workorder.updated",
      "workorder.status_changed",
      "workorder.completed"
    ]
  }'
```

### Step 2: Webhook Receiver (Express)

```typescript
// src/webhook-server.ts
import express from 'express';
import crypto from 'node:crypto';

const app = express();
app.use(express.json({ limit: '1mb' }));

// Signature verification middleware
function verifySignature(secret: string) {
  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
    const signature = req.headers['x-maintainx-signature'] as string;
    if (!signature) {
      return res.status(401).json({ error: 'Missing signature header' });
    }

    const expected = crypto
      .createHmac('sha256', secret)
      .update(JSON.stringify(req.body))
      .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
    next();
  };
}

const WEBHOOK_SECRET = process.env.MAINTAINX_WEBHOOK_SECRET!;

app.post(
  '/webhooks/maintainx',
  verifySignature(WEBHOOK_SECRET),
  async (req, res) => {
    const { event, data, timestamp } = req.body;

    console.log(`[${timestamp}] Event: ${event}, Resource ID: ${data.id}`);

    // Idempotency check
    const eventId = req.headers['x-maintainx-event-id'] as string;
    if (await isProcessed(eventId)) {
      return res.status(200).json({ status: 'already_processed' });
    }

    try {
      await routeEvent(event, data);
      await markProcessed(eventId);
      res.status(200).json({ status: 'ok' });
    } catch (err) {
      console.error('Webhook handler error:', err);
      res.status(500).json({ error: 'Processing failed' });
    }
  },
);

app.listen(3000, () => console.log('Webhook server listening on :3000'));
```

### Step 3: Event Router

```typescript
// src/event-handlers.ts

type EventHandler = (data: any) => Promise<void>;

const handlers: Record<string, EventHandler> = {
  'workorder.created': async (data) => {
    console.log(`New work order: #${data.id} "${data.title}"`);
    // Notify Slack, create ticket, etc.
    if (data.priority === 'HIGH') {
      await sendSlackAlert(`High priority WO created: ${data.title}`);
    }
  },

  'workorder.status_changed': async (data) => {
    console.log(`WO #${data.id}: ${data.previousStatus} → ${data.status}`);
    if (data.status === 'COMPLETED') {
      await syncCompletionToERP(data);
    }
  },

  'workorder.completed': async (data) => {
    console.log(`WO #${data.id} completed at ${data.completedAt}`);
    await generateCompletionReport(data);
  },

  'workorder.updated': async (data) => {
    await syncWorkOrderToDataWarehouse(data);
  },
};

export async function routeEvent(event: string, data: any) {
  const handler = handlers[event];
  if (handler) {
    await handler(data);
  } else {
    console.warn(`Unhandled event type: ${event}`);
  }
}
```

### Step 4: Idempotency Store

```typescript
// src/idempotency.ts
// Use Redis in production; Map for dev/testing
const processed = new Map<string, boolean>();

export async function isProcessed(eventId: string): Promise<boolean> {
  return processed.has(eventId);
}

export async function markProcessed(eventId: string): Promise<void> {
  processed.set(eventId, true);
  // In production: await redis.setex(`event:${eventId}`, 86400, '1');
}
```

### Step 5: Local Development with ngrok

```bash
# Start your webhook server
npm run dev

# In another terminal, expose it with ngrok
ngrok http 3000
# Copy the https URL (e.g., https://abc123.ngrok-free.app)

# Register the ngrok URL as a webhook
curl -X POST https://api.getmaintainx.com/v1/webhooks \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok-free.app/webhooks/maintainx",
    "events": ["workorder.created", "workorder.status_changed"]
  }'
```

### Step 6: List and Manage Webhooks

```bash
# List all registered webhooks
curl -s https://api.getmaintainx.com/v1/webhooks \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" | jq .

# Delete a webhook (replace ID)
curl -X DELETE https://api.getmaintainx.com/v1/webhooks/456 \
  -H "Authorization: Bearer $MAINTAINX_API_KEY"
```

## Output

- Webhook endpoint with HMAC signature verification
- Event router dispatching to type-specific handlers
- Idempotency guard preventing duplicate processing
- Local dev setup with ngrok for testing webhooks
- Webhook registration and management via REST API

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| 401 on webhook registration | Invalid API key | Verify `MAINTAINX_API_KEY` |
| Webhook not firing | URL not reachable | Ensure HTTPS, check firewall, test with ngrok |
| Duplicate events | Retries from MaintainX | Implement idempotency with event ID deduplication |
| Signature mismatch | Wrong secret or body mutation | Verify raw body is used for HMAC, check secret value |

## Resources

- MaintainX API Reference
- [ngrok Documentation](https://ngrok.com/docs)
- [Webhook Security Best Practices](https://hookdeck.com/webhooks/guides/webhook-security-vulnerabilities-guide)

## Next Steps

For performance optimization, see `maintainx-performance-tuning`.

## Examples

**Slack notification on high-priority work orders**:

```typescript
async function sendSlackAlert(message: string) {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `:rotating_light: MaintainX Alert: ${message}`,
    }),
  });
}
```

**Polling fallback when webhooks are unavailable**:

```typescript
// Poll every 60 seconds for status changes
async function pollWorkOrders(client: MaintainXClient, since: string) {
  const { workOrders } = await client.getWorkOrders({
    updatedAtGte: since,
    limit: 50,
  });
  for (const wo of workOrders) {
    await routeEvent('workorder.updated', wo);
  }
  return new Date().toISOString();
}
```

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

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

Все скиллы по теме «Бэкенд и API» →
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установок slack-webhooks hookdeck Скилл slack-webhooks помогает настроить приём вебхуков Slack Events API, пройти проверку url_verification и настроить валидацию подписи запросов. CX Codex +1 128установок stripe-webhooks hookdeck Скилл stripe-webhooks для Claude Code: проверяет подписи, разбирает события и даёт готовые обработчики вебхуков Stripe. Отлаживает платёжные события, не прошедшие проверку. CX Codex +1 604установок inngest-events inngest Скилл inngest-events помогает проектировать событийные воркфлоу Inngest: имена событий, идемпотентность по id, fan-out и системные события. CX Codex +1 4 000установок nodejs-backend-patterns Seth Hobson Скилл nodejs-backend-patterns подсказывает агенту, как строить серверы на Express и Fastify: middleware, обработка ошибок, авторизация, работа с базами. CX Codex +1 48 535установок webhook-receiver-hardener patricio0312rev Скилл webhook-receiver-hardener помогает проектировать защищённые эндпоинты для вебхуков. Защищает обработчики от подделки запросов, повторных доставок и сбоев сторонних сервисов. CX Codex +1 287установок

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

Весь набор →
evernote-core-workflow-a Скилл evernote-core-workflow-a для Claude Code создаёт заметки Evernote и управляет блокнотами и тегами в базовом рабочем процессе, включая форматирование ENML и группировку блокнотов в стеки. CX Codex +1 1установок backlog-grooming-assistant Скилл backlog-grooming-assistant помогает структурировать бэклог, готовит конфигурации задач и даёт пошаговые инструкции для груминга в enterprise-проектах. CX Codex +1 1установок long-polling-handler Автоматически помогает разбирать задачи long polling handler в API-интеграциях, писать конфигурации и проверять результат. CX Codex +1 1установок emitting-api-events Скилл emitting-api-events для проектирования событийно-ориентированных API. Добавляет вебхуки, Server-Sent Events и интеграцию с брокерами сообщений в существующий бэкенд. CX Codex +1 1установок lindy-webhooks-events Скилл lindy-webhooks-events для Claude Code подключает вебхук-триггеры Lindy AI и обратные вызовы приложения. Проверяет события, ставит их в очередь и обрабатывает повторные запросы. CX Codex +1 1установок fireflies-webhooks-events Скилл fireflies-webhooks-events проводит агента по сборке приёмника Fireflies Webhooks V2: проверка HMAC по сырому телу, белый список событий, дедупликация и быстрый ответ 2xx. CX Codex +1 1установок documenso-webhooks-events Скилл documenso-webhooks-events помогает настроить приём вебхуков сервиса Documenso. Пригодится при отслеживании подписания документов и передаче статусов во внешние сервисы. CX Codex +1 1установок windsurf-webhooks-events Скилл windsurf-webhooks-events для Claude Code создаёт расширения Windsurf на основе VS Code API и отправляет события рабочей области во внешнюю систему. Отслеживает сохранения, смену редактора и вывод терминала. CX Codex +1 1установок

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

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