mailersend-webhooks

MailerSend Webhooks

When to Use This Skill

• How do I receive MailerSend webhooks?
• How do I verify a MailerSend webhook signature?
• Why is my MailerSend Signature header verification failing?
• Why won't my MailerSend webhook save / why does the URL validation fail?
• What is webhook.test and the test_Am3L1GuOIc4blLUuHqAPxxwkZaJyEk8G secret?
• How do I handle activity.hard_bounced / activity.spam_complaint events?
• How do I handle MailerSend SMS webhooks (sms.sent, sms.delivered, sms.failed)?

MailerSend, not MailerLite. MailerSend is the transactional email and SMS API from the MailerLite group (developers.mailersend.com). MailerLite (marketing email) is a separate product with a separate webhook scheme. This skill is not for Mailgun, Mailchimp or Resend either.

Verification (core)

Signature: <lowercase hex HMAC-SHA256 of the RAW request body>, keyed with the per-webhook Signing Secret. No timestamp, no nonce, no version prefix, no field concatenation — the header value is the bare digest.

const crypto = require('crypto');

// MailerSend signs its URL-validation ping with this FIXED, PUBLICLY DOCUMENTED
// secret — not your signing secret. Accept it, but only for `webhook.test`.
const MAILERSEND_TEST_SECRET = 'test_Am3L1GuOIc4blLUuHqAPxxwkZaJyEk8G';

function verifySignature(rawBody, signature, secret) {
  if (!signature || !secret) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(String(signature).trim().toLowerCase(), 'utf8');
  const b = Buffer.from(expected, 'utf8');
  // timingSafeEqual THROWS on a length mismatch — guard the length first
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody MUST be the exact bytes received. Re-serialising parsed JSON breaks it.
const signature = req.header('Signature');
const signedByYou = verifySignature(rawBody, signature, process.env.MAILERSEND_WEBHOOK_SECRET);
const signedByPing = !signedByYou && verifySignature(rawBody, signature, MAILERSEND_TEST_SECRET);
if (!signedByYou && !signedByPing) return res.status(401).send('Invalid signature');
// After parsing: if signedByPing, require type === 'webhook.test' — the test
// secret is public, so it must never authorise a real event.