Amazon SES webhooks
Last verified against Amazon SES's documentation on September 27, 2026.
Amazon SES doesn’t call your webhook directly. It publishes email events such as bounces, complaints, and deliveries to an Amazon SNS topic, and SNS delivers them to your HTTPS endpoint. That adds two things to handle: a subscription confirmation handshake before anything flows, and an SNS signature wrapped around every SES event. SNS’s default retries for HTTPS endpoints also last only about a minute. This page covers what SES sends, how SNS delivers it, how to fix the common errors, and where HookDeploy fits.
What Amazon SES sends
SES can publish events two ways, both through SNS.
Configuration set event destinations cover the full event set:
| Event | Typical use |
|---|---|
Send, Delivery, DeliveryDelay | Track delivery status |
Bounce, Complaint, Reject | Suppress bad addresses and protect your sender reputation |
Open, Click | Measure engagement |
RenderingFailure | Catch broken templates |
Subscription | Sync subscription preferences |
Account-level notifications (feedback notifications) send Bounce, Complaint, and Delivery notifications for an identity.
Either way, the SES event arrives as a JSON string in the Message field of an SNS message.
How SNS delivers to HTTPS endpoints
| Behavior | Detail |
|---|---|
| Method and format | POST. The body is JSON, but the Content-Type is text/plain; charset=UTF-8 by default |
| Message types | SubscriptionConfirmation, Notification, and UnsubscribeConfirmation, also given in the x-amz-sns-message-type header |
| Subscription | Nothing is delivered until you visit the SubscribeURL from the confirmation message |
| Signature | An X.509 signature over the message’s fields. SignatureVersion 1 uses SHA1, version 2 uses SHA256. The certificate is at SigningCertURL |
| Default retries | 3 retries, 20 seconds apart, for HTTP and HTTPS endpoints |
| Custom retries | A delivery policy on the subscription or topic, plus an optional dead-letter queue |
| Deduplication | MessageId, also in the x-amz-sns-message-id header. It stays the same when SNS retries |
Common Amazon SES webhook errors and how to fix them
No events arrive
The subscription is probably still pending. SNS sends one SubscriptionConfirmation message and delivers nothing until someone visits its SubscribeURL. See Confirming the SNS subscription.
The body parser returns nothing
SNS sends JSON with a text/plain content type, so a JSON-only body parser skips it. Read the body as text and parse it yourself, or set headerContentType in the subscription’s delivery policy.
Signature verification fails
- Wrong string to sign. SNS signs a canonical string of specific fields in a specific order, which differs between
NotificationandSubscriptionConfirmationmessages. Use a maintained library. - Wrong algorithm. Check
SignatureVersion: 1 is SHA1 and 2 is SHA256. - Raw message delivery is on. With raw message delivery, SNS sends only the message, without the signature envelope. Leave it off if you verify signatures.
Events lost during an outage
With the default policy, SNS gives up on an HTTPS endpoint after about a minute. Set a longer delivery policy and a dead-letter queue, or put something in front of your server that stays up.
The SES event looks like a string
It is. Parse the SNS body, then parse its Message field again.
Why use HookDeploy with Amazon SES
Stop losing events after a minute
HookDeploy captures every SNS message at Cloudflare’s edge and responds right away, before forwarding it to your server. SNS’s short default retry window stops mattering, because the message is already safe 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.
- History. HookDeploy keeps captured messages for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
Confirm subscriptions without writing code
The SubscriptionConfirmation message lands in HookDeploy like any other request. Open it in the request inspector, copy the SubscribeURL, and you’re subscribed. No confirmation handler required.
Signatures survive retries and replays
SNS signs the message’s fields, and HookDeploy forwards the body unchanged, so retries and replays verify exactly like the original delivery.
Deliver to private infrastructure
SNS can only deliver to public HTTPS endpoints. The HookDeploy Agent connects outward from your network over mTLS and delivers SES events to a local port, so a service in a private subnet can receive them with no public endpoint.
One subscription, many systems
Send each bounce and complaint to your app, your suppression service, and an alert channel 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.
Know the limits
- Transformations. A transformation changes the message, and its signature won’t verify at that destination.
- Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which SNS retries only briefly. Paid plans keep accepting traffic past the included volume.
Confirming the SNS subscription
When you subscribe an HTTPS endpoint to a topic, SNS sends a SubscriptionConfirmation message with a SubscribeURL. Confirm it one of two ways:
- From HookDeploy. Open the captured request in the inspector, copy the
SubscribeURLfrom the body, and open it in a browser. The subscription moves from pending to confirmed. - From your handler. HookDeploy forwards the confirmation message like any other. Verify its signature, check that the
SubscribeURLhost is ansns.amazonaws.comhost, and make aGETrequest to it.
Only confirm messages whose TopicArn is one of your topics.
Set up Amazon SES with HookDeploy
- In HookDeploy, create an endpoint (for example,
SES 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 Amazon SNS, create a topic, and add an HTTPS subscription with your HookDeploy URL. Leave raw message delivery off.
- Open the
SubscriptionConfirmationrequest in HookDeploy and visit itsSubscribeURL. - In Amazon SES, add an SNS event destination to your configuration set, or set up notifications for your identity, pointing to that topic.
- Send a test email, for example to the SES mailbox simulator, and confirm the events appear in HookDeploy and reach your handler.
Example handler (Node.js and Express)
import express from 'express';
import MessageValidator from 'sns-validator';
const app = express();
const validator = new MessageValidator(); // checks the certificate host and the signature
const MY_TOPICS = new Set([process.env.SES_TOPIC_ARN]);
// SNS sends JSON with a text/plain content type.
app.post('/webhooks/ses', express.text({ type: '*/*' }), (req, res) => {
let message;
try {
message = JSON.parse(req.body);
} catch {
return res.status(400).send('Invalid JSON');
}
validator.validate(message, async (err, verified) => {
if (err || !MY_TOPICS.has(verified.TopicArn)) return res.status(401).send('Invalid message');
if (verified.Type === 'SubscriptionConfirmation') {
await fetch(verified.SubscribeURL); // host already checked by the validator
return res.sendStatus(200);
}
res.sendStatus(200);
if (verified.Type === 'Notification') {
const sesEvent = JSON.parse(verified.Message); // the SES event is a JSON string
await enqueue({ messageId: verified.MessageId, type: sesEvent.eventType ?? sesEvent.notificationType, sesEvent });
// Deduplicate on messageId in your worker.
}
});
});
FAQ
Does Amazon SES send webhooks directly?
No. SES publishes email events to an Amazon SNS topic, through a configuration set event destination or account-level notifications, and SNS delivers them to your HTTPS endpoint. What arrives at your endpoint is an SNS message with the SES event inside it.
How do I confirm an SNS subscription to HookDeploy?
When you subscribe the HookDeploy URL, SNS sends a SubscriptionConfirmation message. Open it in HookDeploy's request inspector, copy the SubscribeURL from the body, and open it in a browser, or let your handler confirm it automatically after it verifies the message.
How do I verify an SNS message?
SNS signs a canonical string built from the message's fields with an X.509 certificate. Download the certificate from SigningCertURL, but only after checking that the URL is an HTTPS URL on an sns.amazonaws.com host, then verify the Signature. SignatureVersion 1 uses SHA1 and version 2 uses SHA256.
Why is the SES event a string inside the SNS message?
SNS wraps whatever SES publishes in its Message field as a JSON string. Parse the SNS body, verify it, then parse Message again to get the SES event.
Does SNS retry failed HTTPS deliveries?
Yes, but by default only briefly. The default delivery policy for HTTP and HTTPS endpoints retries 3 times, 20 seconds apart. You can set a longer delivery policy on the subscription and attach a dead-letter queue.
Does HookDeploy break SNS signature verification?
No. SNS signs the message's fields, not the raw bytes, and HookDeploy forwards the body unchanged, so first deliveries, retries, and replays all verify. Don't use a transformation on a destination that verifies the signature.