Skip to main content
skill CX Codex

postmark-webhooks — Claude Code skill: what it does, how to install

A skill for Claude Code that configures handlers for Postmark webhooks. It processes bounces, opens, clicks, spam complaints, and inbound messages.

MIT 203 installs ★ 103 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a claude-code
Open on GitHub

What postmark-webhooks does

The skill generates server routes and validation logic for incoming Postmark events. Postmark sends individual events per request instead of batching them. Handled types include deliveries, soft and hard bounces, link clicks, open tracking, and subscription changes.

Postmark does not sign webhook payloads with HMAC secrets. Verification relies on query parameters like POSTMARK_WEBHOOK_TOKEN, basic authentication, or custom HTTP headers. Inbound email payloads omit the RecordType field entirely, so the code identifies them through FromFull. Payloads for SubscriptionChange often set MessageID to null, and responding with any 4xx status causes Postmark to discard the event immediately.

Local request inspection uses npx hookdeck-cli listen 3000 postmark --path /webhooks/postmark, which requires no account.

What it helps with

  • set up webhook endpoints for Postmark delivery and bounce events
  • authenticate webhooks via URL query tokens or Basic Auth without signatures
  • distinguish inbound email payloads lacking a RecordType field
  • test incoming email webhooks locally using Hookdeck CLI

Example prompts for the agent

  • Create an Express route to process Postmark Bounce and Open events
  • Add validation for Postmark webhooks using a URL secret token
  • How do I inspect Postmark webhooks on localhost during development?

How to install postmark-webhooks

1Skills CLI (Vercel)

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

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/postmark-webhooks/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about postmark-webhooks

How to install postmark-webhooks in Claude Code?

Run npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a claude-code in your terminal. This saves the skill to ~/.claude/skills/postmark-webhooks/SKILL.md.

What does postmark-webhooks do?

It provides implementation patterns and validation logic for handling Postmark event notifications across backend frameworks.

How does Postmark authenticate webhooks?

Postmark skips HMAC signatures, requiring developers to authenticate requests via URL query tokens, Basic Auth, or IP address whitelisting.

Source text

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

Similar skills

All skills for Backend and APIs →

From the same set39

The whole set →
hookdeck-event-gateway Connects Hookdeck Event Gateway — webhook infrastructure with queue, retries and monitoring. CX Codex +1 214installs woocommerce-webhooks Sets up and validates WooCommerce webhooks in Node.js and Python. Handles signature verification and store events like order or product updates. CX Codex +1 213installs clerk-webhooks This skill guides you through receiving Clerk webhooks and checking their signatures. Use it when building handlers for user, session, or organization events. CX Codex +1 210installs vercel-webhooks Skill for receiving and verifying Vercel webhooks directly in code. Handles webhook setup, signature verification debugging, and reacting to deployment and project events. CX Codex +1 204installs openai-webhooks A skill for receiving and verifying OpenAI webhooks. Use it to process fine-tuning events, batch completions, and realtime API callbacks with built-in signature validation. CX Codex +1 202installs cursor-webhooks Set up a handler for Cursor Cloud Agent webhooks, verify request signatures, and respond to agent status changes. Useful when wiring webhook events into an app. CX Codex +1 200installs deepgram-webhooks A skill for receiving and verifying Deepgram webhooks. Use when you need to handle asynchronous transcription results or build a callback handler for completed transcription requests. CX Codex +1 200installs gitlab-webhooks Skill for handling GitLab webhooks with signature and token verification. Use it to set up webhook handlers for push, merge request, and pipeline events, or debug authentication failures. CX Codex +1 199installs

Project sponsors

Companies that keep this analytics open