postmark-webhooks — скилл для Claude Code: что делает и как установить
Скилл postmark-webhooks для Claude Code помогает принимать и обрабатывать вебхуки Postmark. Настраивает обработку доставок, кликов, открытий, жалоб на спам и входящих сообщений.
MIT 203 установок ★ 103 обновлён 2026-11-16
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a claude-codeЧто делает postmark-webhooks
Скилл генерирует маршруты и валидаторы для входящих событий почтового сервиса Postmark. Сервис отправляет каждое событие отдельным HTTP-запросом без объединения в пачки: доставки, отскоки, открытия, переходы по ссылкам и смену подписки.
В Postmark нет цифровых подписей для верификации запросов. Авторизацию настраивают через секретный токен в строке запроса, Basic Auth или кастомные заголовки HttpHeaders. Код скилла сразу учитывает граничные случаи: у входящих писем нет поля RecordType, поэтому их определяют по наличию FromFull, а у событий SubscriptionChange идентификатор MessageID может быть пустым. Если вернуть статус 4xx, Postmark просто отбросит событие без повторов.
Для локальной отладки маршрутов скилл предлагает проброс через команду npx hookdeck-cli listen 3000 postmark --path /webhooks/postmark без регистрации аккаунта.
Какие задачи решает
- настроить эндпоинт для приёма отскоков и спам-жалоб Postmark
- валидировать вебхуки через токен в URL или Basic Auth без цифровой подписи
- разобрать полезную нагрузку входящих писем по полю FromFull
- настроить локальный туннель для тестирования хуков через Hookdeck CLI
Примеры запросов агенту
- Напиши Express-обработчик для вебхуков Postmark с проверкой токена в URL
- Добавь разбор событий Bounce и SpamComplaint из вебхука Postmark
- Как протестировать приём входящих вебхуков Postmark локально?
Как установить postmark-webhooks
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a claude-code2Вручную: положить файлы
~/.claude/skills/postmark-webhooks/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/postmark-webhooks/
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a codex2Вручную: положить файлы
.agents/skills/postmark-webhooks/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a cursor2Вручную: положить файлы
.cursor/skills/postmark-webhooks/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills skills/postmark-webhooks2Вручную: положить файлы
.github/skills/postmark-webhooks/SKILL.md1Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a gemini-cli2Командой платформы
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/postmark-webhooksВручную: положить файлы
.devin/skills/postmark-webhooks/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о postmark-webhooks
Как установить postmark-webhooks в Claude Code?
Выполните в терминале команду npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a claude-code. Скилл запишется в папку ~/.claude/skills/postmark-webhooks/SKILL.md.
Что делает postmark-webhooks?
Даёт инструкции и готовые шаблоны кода для безопасной обработки всех типов вебхуков Postmark, отслеживания доставки и фиксации входящих писем.
Как проверять подлинность вебхуков Postmark?
Postmark не использует HMAC-сигнатуры. Проверка строится на токене в переменной POSTMARK_WEBHOOK_TOKEN, Basic Auth либо разрешённом диапазоне IP-адресов сервиса.
Исходный текст
SKILL.md · MIT
--- name: postmark-webhooks description: > Receive and process Postmark webhooks. Use when setting up Postmark webhook handlers, handling email delivery events, processing bounces, opens, clicks, spam complaints, or subscription changes. license: MIT metadata: author: hookdeck version: "0.1.0" repository: https://github.com/hookdeck/webhook-skills --- # Postmark Webhooks ## When to Use This Skill - Setting up Postmark webhook handlers for email event tracking - Processing email delivery events (bounce, delivered, open, click) - Handling spam complaints and subscription changes - Implementing email engagement analytics - Troubleshooting webhook authentication issues ## Essential Code ### Authentication Postmark does NOT use signature verification. Instead, webhooks are authenticated with credentials you configure on the webhook: Basic Auth or a token in the URL (shown below), or a custom header set with `HttpHeaders` (see [references/verification.md](references/verification.md)). ```javascript // Express - Basic Auth in URL // Configure webhook URL in Postmark as: // https://username:[email protected]/webhooks/postmark app.post('/webhooks/postmark', express.json(), (req, res) => { // Basic auth is handled by your web server or proxy // Additional validation can check expected payload structure const event = req.body; // Validate expected fields exist (Inbound payloads have no RecordType). // SubscriptionChange can have MessageID: null, and a 4xx makes Postmark drop the event. const recordType = event.RecordType || (event.FromFull ? 'Inbound' : undefined); if (!recordType || (recordType !== 'SubscriptionChange' && !event.MessageID)) { return res.status(400).send('Invalid payload structure'); } // Process event console.log(`Received ${event.RecordType || 'Inbound'} event for message ${event.MessageID}`); res.sendStatus(200); }); // Alternative: Token in URL // Configure webhook URL as: // https://yourdomain.com/webhooks/postmark?token=your-secret-token app.post('/webhooks/postmark', express.json(), (req, res) => { const token = req.query.token; const expectedToken = process.env.POSTMARK_WEBHOOK_TOKEN; // Fail closed: never accept a request when no token is configured if (!expectedToken || token !== expectedToken) { return res.status(401).send('Unauthorized'); } const event = req.body; console.log(`Received ${event.RecordType || 'Inbound'} event`); res.sendStatus(200); }); ``` ### Handling Multiple Events ```javascript // Postmark sends one event per request (not batched) app.post('/webhooks/postmark', express.json(), (req, res) => { const event = req.body; // Inbound webhooks have no RecordType, so identify them by FromFull const recordType = event.RecordType || (event.FromFull ? 'Inbound' : undefined); switch (recordType) { case 'Bounce': console.log(`Bounce: ${event.Email} - ${event.Type} - ${event.Description}`); // Update contact as undeliverable break; case 'SpamComplaint': console.log(`Spam complaint: ${event.Email}`); // Remove from mailing list break; case 'Open': console.log(`Email opened: ${event.Recipient} at ${event.ReceivedAt}`); // Track engagement break; case 'Click': console.log(`Link clicked: ${event.Recipient} - ${event.OriginalLink}`); // Track click-through rate break; case 'Delivery': console.log(`Delivered: ${event.Recipient} at ${event.DeliveredAt}`); // Confirm delivery break; case 'SubscriptionChange': console.log(`Subscription change: ${event.Recipient} - ${event.ChangedAt}`); // Update subscription preferences break; case 'Inbound': console.log(`Inbound email from: ${event.From} - Subject: ${event.Subject}`); // Process incoming email break; case 'SMTP API Error': // Postmark publishes no sample payload for this webhook: check these // names against a real delivery console.log(`SMTP API error: ${event.Email} - ${event.Error}`); // Handle API error, maybe retry break; default: console.log(`Unknown event type: ${recordType}`); } res.sendStatus(200); }); ``` ## Common Event Types | Event | RecordType | Description | Key Fields | |-------|------------|-------------|------------| | Bounce | `Bounce` | Hard/soft bounce or blocked email | Email, Type, TypeCode, Description | | Spam Complaint | `SpamComplaint` | Recipient marked as spam | Email, BouncedAt | | Open | `Open` | Email opened (requires open tracking) | Recipient, ReceivedAt, Platform, UserAgent | | Click | `Click` | Link clicked (requires click tracking) | Recipient, ReceivedAt, OriginalLink | | Delivery | `Delivery` | Successfully delivered | Recipient, DeliveredAt, Details | | Subscription Change | `SubscriptionChange` | Unsubscribe/resubscribe | Recipient, ChangedAt, SuppressionReason | | Inbound | None | Incoming email received | From, FromFull, Subject, TextBody, HtmlBody | | SMTP API Error | `SMTP API Error` | SMTP API call failed | Email, Error, ErrorCode, MessageID | Inbound payloads have no `RecordType`, so identify them by `FromFull`. Postmark publishes no sample payload for SMTP API Error, so check that row's `RecordType` and fields against a real delivery. ## Environment Variables ```bash # For token-based authentication POSTMARK_WEBHOOK_TOKEN="your-secret-token-here" # For basic auth (if not using URL-embedded credentials) WEBHOOK_USERNAME="your-username" WEBHOOK_PASSWORD="your-password" ``` ## Security Best Practices 1. **Always use HTTPS** - Never configure webhooks with HTTP URLs 2. **Use strong credentials** - Generate long, random tokens or passwords 3. **Validate payload structure** - Check for expected fields before processing 4. **Implement IP allowlisting** - Postmark publishes their IP ranges 5. **Consider using a webhook gateway** - Like Hookdeck for additional security layers ## Local Development For local webhook testing, use Hookdeck CLI: ```bash npx hookdeck-cli listen 3000 postmark --path /webhooks/postmark ``` No account required. Provides local tunnel + web UI for inspecting requests. ## Resources - [overview.md](references/overview.md) - What Postmark webhooks are, common event types - [setup.md](references/setup.md) - Configure webhooks in Postmark dashboard - [verification.md](references/verification.md) - Authentication methods and security best practices - [examples/](examples/) - Complete implementations for Express, Next.js, and FastAPI ## Recommended: webhook-handler-patterns For production-ready webhook handling, also install the webhook-handler-patterns skill: - [Handler sequence](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/handler-sequence.md) - Webhook processing flow - [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) - Graceful error recovery - [Retry logic](https://github.com/hookdeck/webhook-skills/blob/main/skills/webhook-handler-patterns/references/retry-logic.md) - Handle transient failures ## Related Skills - [sendgrid-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/sendgrid-webhooks) - SendGrid webhook handling with ECDSA verification - [resend-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/resend-webhooks) - Resend webhook handling with Svix signatures - [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe webhook handling with HMAC-SHA256 - [webhook-handler-patterns](https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns) - Idempotency, error handling, retry logic - [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Production webhook infrastructure
© hookdeck · MIT · hookdeck/webhook-skills