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
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/postmark-webhooks/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/postmark-webhooks/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a codex2Manually: put the files in place
.agents/skills/postmark-webhooks/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a cursor2Manually: put the files in place
.cursor/skills/postmark-webhooks/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install hookdeck/webhook-skills skills/postmark-webhooks2Manually: put the files in place
.github/skills/postmark-webhooks/SKILL.md1Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a gemini-cli2Platform CLI
gemini skills install https://github.com/hookdeck/webhook-skills --path skills/postmark-webhooksManually: put the files in place
.devin/skills/postmark-webhooks/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add hookdeck/webhook-skills --skill postmark-webhooks -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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