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

postmark-webhooks — скилл для Claude Code: что делает и как установить

Скилл postmark-webhooks для Claude Code помогает принимать и обрабатывать вебхуки Postmark. Настраивает обработку доставок, кликов, открытий, жалоб на спам и входящих сообщений.

MIT 203 установок ★ 103 обновлён 2026-11-16

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

Что делает 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-code

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

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

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

По шагам, с командами для каждой платформы: Как установить скилл в 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

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

Все скиллы по теме «Бэкенд и API» →
postmark postmark Скилл-маршрутизатор по Postmark: подсказывает агенту, какой под-скилл взять для отправки писем, входящих, шаблонов и вебхуков. CX Codex +1 816установок postmark-automation davepoon Скилл postmark-automation гоняет Postmark через Rube MCP: отправка писем по шаблонам, правка шаблонов, статистика доставки и разбор bounce'ов прямо из чата с агентом. CX Codex +1 120установок 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установок 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установок pipefy-members-email-webhooks pipefy Скилл pipefy-members-email-webhooks для Claude Code управляет участниками пайпов Pipefy, письмами из карточного инбокса и вебхуками. Включается для приглашения пользователя, отправки письма или регистрации endpoint. CX Codex +1 782установок

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

Весь набор →
hookdeck-event-gateway Подключает Hookdeck Event Gateway — инфраструктуру приёма вебхуков с очередью, повторами и мониторингом. CX Codex +1 214установок woocommerce-webhooks Скилл woocommerce-webhooks помогает принимать и проверять вебхуки WooCommerce в Node.js и Python. Защищает эндпоинты через сверку HMAC-подписей событий заказов и товаров. CX Codex +1 213установок clerk-webhooks Скилл clerk-webhooks помогает написать обработчик вебхуков Clerk и проверить подпись запроса. Пригодится при настройке событий пользователей, сессий и организаций. CX Codex +1 210установок vercel-webhooks Скилл vercel-webhooks для приёма и проверки вебхуков Vercel прямо в коде. Помогает при настройке обработчиков, отладке проверки подписей и реагировании на события развёртывания и проектов. CX Codex +1 204установок openai-webhooks Скилл openai-webhooks для Claude Code принимает и проверяет вебхуки OpenAI. Обрабатывает события fine-tuning, batch API и realtime API с проверкой подписей. CX Codex +1 202установок cursor-webhooks Скилл cursor-webhooks помогает настроить приём вебхуков Cursor Cloud Agent, проверить подпись и обработать смену статуса. Пригодится при подключении обработчика к проекту. CX Codex +1 200установок deepgram-webhooks Скилл deepgram-webhooks для Claude Code принимает и проверяет вебхуки Deepgram. Обрабатывает асинхронные результаты транскрипции и колбэки завершённых запросов. CX Codex +1 200установок gitlab-webhooks Скилл gitlab-webhooks для Claude Code обрабатывает вебхуки GitLab с проверкой подписей и токенов. Помогает отлаживать верификацию вебхуков для push-событий, merge-request и pipeline. CX Codex +1 199установок

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

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