Agent skill
Mailcoach Webhooks Skill
Receive and verify Mailcoach webhooks. Use when setting up Mailcoach webhook handlers, debugging Signature header verification, or handling SubscribedEvent, UnsubscribedEvent, UnconfirmedSubscriberCreatedEvent and CampaignSentEvent events from Mailcoach email marketing.
Install this skill
npx skills add hookdeck/webhook-skills --skill mailcoach-webhooks
Mailcoach (email marketing by Spatie, hosted or self-hosted) sends an HTTP POST with a JSON body to your endpoint when a subscriber joins or leaves a list or a campaign finishes sending. If you set a secret on the webhook, each request carries a Signature header with an HMAC-SHA256 of the body.
When to Use This Skill
- How do I receive Mailcoach webhooks?
- How do I verify the Mailcoach
Signatureheader? - Why is my Mailcoach webhook signature verification failing?
- How do I handle
SubscribedEvent,UnsubscribedEventorCampaignSentEvent? - Why do unsigned Mailcoach deliveries fail verification?
Set a secret on the Mailcoach webhook. Without one, deliveries are unsigned and fail verification.
Verification (core)
Signature: <hex> is the lowercase hex HMAC-SHA256 of the raw request body bytes, keyed with the secret as UTF-8 (not hex- or base64-decoded). There is no prefix, and no timestamp or id is signed. Compare the whole header value as one digest.
Node (validate the 64-hex shape before comparing):
const crypto = require('crypto');
function verify(rawBody, signatureHeader, secret) {
if (!signatureHeader || !secret || !/^[0-9a-f]{64}$/i.test(signatureHeader)) return false;
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signatureHeader.toLowerCase(), 'utf8'),
Buffer.from(expected, 'utf8')
);
}
Python (compare bytes, never str, so a non-ASCII header gives a 401, not a 500):
import hmac, hashlib, re
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
if not signature_header or not re.fullmatch(r"[0-9a-fA-F]{64}", signature_header):
return False
computed = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature_header.lower().encode("ascii"), computed.encode("ascii"))
Return 401 for a missing, empty, malformed or mismatching Signature. In Express use express.raw({ type: '*/*' }); in Next.js use await request.arrayBuffer(); in FastAPI use await request.body(). Parse the JSON only after the check.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Common Event Types
The event name is the event field in the JSON body (the PHP event class name); no header carries it. Mailcoach documents four:
| Event | Description |
|---|---|
UnconfirmedSubscriberCreatedEvent | Someone was added to a list that uses confirmation; not confirmed yet |
SubscribedEvent | A subscriber was confirmed |
UnsubscribedEvent | Someone unsubscribed |
CampaignSentEvent | A campaign has been fully sent |
Subscriber events carry email_list_uuid, email, first_name, last_name, extra_attributes, tags, subscribed_at, unsubscribed_at, created_at, updated_at. CampaignSentEvent carries the campaign fields (uuid, name, sent_, open and click statistics, sent_at, ...). Handle the ones you need and log the rest. See references/overview.md.
Important Headers
| Header | Description |
|---|---|
Signature | Hex HMAC-SHA256 of the raw body (only sent when a secret is set) |
Header names are case-insensitive.
Setup with Hookdeck
In Mailcoach, open Settings > Webhooks, create a webhook with your Hookdeck source URL, and set a secret on its details page. Set a secret on the Mailcoach webhook. Without one, deliveries are unsigned and fail verification. Use the same secret as the Hookdeck source's signing secret (Mailcoach source type). See references/setup.md.
Environment Variables
MAILCOACH_WEBHOOK_SECRET=your_webhook_secret # Secret entered on the Mailcoach webhook details page
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 mailcoach --path /webhooks/mailcoach
Reference Materials
- references/overview.md - Mailcoach webhook concepts, events and payloads
- references/setup.md - Creating the webhook and secret
- references/verification.md - Signature verification details