Mautic Webhooks Skill

When to Use This Skill

• How do I receive Mautic webhooks?
• How do I verify the Mautic Webhook-Signature header?
• Why does my Mautic webhook signature verification fail?
• How do I handle mautic.lead_post_save_new or mautic.form_on_submit events?
• How do I process batched events from Mautic's queue mode?

Verification (core)

Mautic computes a base64 HMAC-SHA256 of the raw request body, keyed with the webhook's secret as a raw string (not decoded, no prefix), and sends it in the Webhook-Signature header. Despite the header name this is not Standard Webhooks: there is no webhook-id or webhook-timestamp, and nothing but the body is signed.

Node:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');
  try {
    return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
  } catch {
    return false; // different lengths
  }
}

Python:

import base64, hashlib, hmac

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header:
        return False
    expected = base64.b64encode(
        hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(signature_header.encode(), expected.encode())

Raw body: read the body as bytes before any JSON parsing, and accept any content type (Express: express.raw({ type: '*/*' })).

For complete handlers with route wiring, event dispatch, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/

Payload Shape

The body is an object keyed by event type; each value is an array of events, each with a timestamp. In queue (background) mode one request can contain several event types and several events per type, so iterate over all keys and all items.

{
  "mautic.lead_post_save_new": [
    { "contact": { "id": 1 }, "timestamp": "2026-01-01T12:00:00+00:00" }
  ]
}

Common Event Types

For payload fields, see Mautic webhook events and payloads.

Environment Variables

MAUTIC_WEBHOOK_SECRET=your_webhook_secret   # Secret shown on the webhook's edit page in Mautic

Local Development

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

Reference Materials

• references/overview.md - Mautic webhook concepts, events, payload structure
• references/setup.md - Create and test a webhook in Mautic
• references/verification.md - Signature verification details and gotchas