MailerSend webhooks
Last verified against MailerSend's documentation on September 27, 2026.
MailerSend sends webhooks for what happens to the email and SMS you send: sent, delivered, bounced, opened, clicked, unsubscribed, and marked as spam. Its signature is simple, an HMAC of the raw body, but two details catch people out: the validation request MailerSend sends when you save a webhook is signed with a different secret, and the signature has no timestamp. This page covers what MailerSend sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What MailerSend sends webhooks for
| Area | Key events | Typical use |
|---|---|---|
| Delivery | activity.sent, activity.delivered, activity.soft_bounced, activity.hard_bounced | Track delivery and suppress bad addresses |
| Engagement | activity.opened, activity.clicked | Measure engagement |
| Recipient actions | activity.unsubscribed, activity.spam_complaint | Keep suppression lists in sync |
| SMS | sms.sent, sms.delivered, sms.failed | Track SMS delivery |
| Account | sender_identity.verified, inbound_forward.failed | Monitor setup and inbound routing |
Every webhook is a JSON POST with a type, a created_at timestamp, and the event under data. Webhooks are configured per domain.
How MailerSend delivers webhooks
| Behavior | Detail |
|---|---|
| Method and format | POST with a JSON body |
| Signature header | Signature |
| Signing scheme | Lowercase hex HMAC-SHA256 of the raw body, keyed with the webhook’s signing secret. No timestamp |
| URL validation | Creating or updating a webhook sends a webhook.test request, signed with MailerSend’s public test secret. The webhook is saved only on a 2xx |
| Retries | Failed deliveries are retried automatically |
| Delivery logs | Requests, including retries, are visible for the past 7 days |
Common MailerSend webhook errors and how to fix them
The webhook won’t save
MailerSend validates your URL with a webhook.test request, signed with its public test secret instead of your webhook’s secret. A handler that rejects every request it can’t verify returns 401, and MailerSend refuses to save the webhook. Acknowledge webhook.test requests with a 2xx without processing them.
Signature verification fails
- The body was parsed first. The HMAC covers the raw bytes. Verify before any JSON middleware.
- Wrong secret. Each webhook has its own signing secret.
- Wrong encoding. The header holds a lowercase hex digest with no prefix.
Payload shape surprises
Some fields don’t match what typed code expects. For example, meta can be null, and created_at appears in more than one date format depending on the event. Normalize the payload before it reaches typed code.
Duplicate events
Retries deliver the same event again. Deduplicate on the ID in the event’s data.
Why use HookDeploy with MailerSend
Keep more than 7 days of history
MailerSend shows delivery logs for 7 days. HookDeploy keeps every captured webhook for your plan’s retention period, from 7 days on Free to 365 days on Enterprise, with the full body and headers.
Capture every event
HookDeploy captures each webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your server is down, events wait in HookDeploy.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
Save webhooks without special-casing the test
HookDeploy answers the webhook.test validation request with a 200, so MailerSend saves the webhook even before your handler exists. Your handler still sees the test request when it’s forwarded, and should acknowledge it.
One webhook, many systems
Send each event to your app, your CRM, and an analytics pipeline in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Develop against real events
A tap sends a temporary copy of live MailerSend events to 127.0.0.1 on your machine while production keeps receiving them.
Know the limits
- Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which MailerSend treats as a failed delivery. Paid plans keep accepting traffic past the included volume.
Retries, replays, and duplicates
MailerSend’s signature covers only the body, with no timestamp, and HookDeploy forwards the body and Signature header unchanged. Retries and replays verify exactly like the original delivery, however old they are.
That also means a valid request can be replayed by anyone who captures it. Deduplicate on the event ID, whether the repeat comes from MailerSend, from HookDeploy, or from somewhere else.
A transformation, or a privacy filter that changes the stored copy used for retries and replays, changes the body, and then the signature won’t match at that destination.
Set up MailerSend with HookDeploy
- In HookDeploy, create an endpoint (for example,
MailerSend events) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- In MailerSend, open your domain’s webhooks and add a webhook with your HookDeploy URL and the events you want. Copy its signing secret.
- Trigger an event, for example by sending a test email, and confirm it appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/mailersend', express.raw({ type: 'application/json' }), async (req, res) => {
const event = JSON.parse(req.body.toString('utf8'));
if (event.type === 'webhook.test') return res.sendStatus(200); // URL validation, other secret
const expected = crypto
.createHmac('sha256', process.env.MAILERSEND_SIGNING_SECRET)
.update(req.body) // raw bytes
.digest('hex');
const received = req.get('signature') ?? '';
const valid =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.status(401).send('Invalid signature');
res.sendStatus(200);
await enqueue({ eventId: event.data?.id, type: event.type, createdAt: event.created_at, data: event.data });
// Deduplicate on eventId in your worker.
});
FAQ
How are MailerSend webhooks signed?
Each request has a Signature header containing a lowercase hex HMAC-SHA256 of the raw request body, keyed with the webhook's signing secret. There's no timestamp or prefix, just the digest.
Why won't MailerSend save my webhook?
When you create or update a webhook, MailerSend validates the URL with a webhook.test request and only saves the webhook if it gets a 2xx. That test is signed with MailerSend's public test secret, not your webhook's secret, so a handler that rejects anything it can't verify blocks the save.
Is MailerSend the same as MailerLite?
No. MailerSend is the transactional email and SMS API from the MailerLite group. MailerLite is a separate marketing email product with its own webhooks.
Does HookDeploy break MailerSend signature verification?
No. The signature covers only the body, with no timestamp, and HookDeploy forwards the body unchanged, so first deliveries, retries, and replays all verify. A transformation or privacy filter changes the body, and then the signature won't match at that destination.
Do MailerSend signatures protect against replayed requests?
Not on their own. With no timestamp or nonce in the signature, a captured request stays valid forever. Deduplicate on the event data's ID, and restrict who can reach your endpoint.
Does MailerSend send SMS webhooks too?
Yes. Besides email activity events, MailerSend sends SMS events such as sms.sent, sms.delivered, and sms.failed, signed the same way.