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 Signature header?
  • Why is my Mailcoach webhook signature verification failing?
  • How do I handle SubscribedEvent, UnsubscribedEvent or CampaignSentEvent?
  • 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:

EventDescription
UnconfirmedSubscriberCreatedEventSomeone was added to a list that uses confirmation; not confirmed yet
SubscribedEventA subscriber was confirmed
UnsubscribedEventSomeone unsubscribed
CampaignSentEventA 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_to_number_of_subscribers, open and click statistics, sent_at, ...). Handle the ones you need and log the rest. See references/overview.md.

Important Headers

HeaderDescription
SignatureHex 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →