# 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):

```javascript
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):

```python
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/mailcoach-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/mailcoach-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/mailcoach-webhooks/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_to_number_of_subscribers`, open and click statistics, `sent_at`, ...). Handle the ones you need and log the rest. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/mailcoach-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/mailcoach-webhooks/references/setup.md).

## Environment Variables

```bash
MAILCOACH_WEBHOOK_SECRET=your_webhook_secret   # Secret entered on the Mailcoach webhook details page

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 mailcoach --path /webhooks/mailcoach

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/mailcoach-webhooks/references/overview.md) - Mailcoach webhook concepts, events and payloads
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/mailcoach-webhooks/references/setup.md) - Creating the webhook and secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/mailcoach-webhooks/references/verification.md) - Signature verification details