Setup AWS SES Web Hooks with SES Monitor

SES Monitor Web Hooks

SES Monitor provides web hook functionality which you can use to receive notifications about critical email deliverability events, such as bounces and complaints. These notifications are usually sent within a few seconds of our systems being made aware of the email event from AWS SES.

A web hook in SES Monitor works by allowing you to provide a URL and select the types of events you'd like to be notified about. When SES Monitor detects the selected event type it triggers an HTTP POST request to the webhook URL you've provided. This request includes a payload containing essential information about the event, such as the recipient's email address, event type, and the timestamp.

By setting up web hooks in SES Monitor, you enable your application or service to receive and process email deliverability events automatically and in real-time. This allows you to act on the events quickly, adjust your email sending strategy accordingly, and ultimately improve your email deliverability and sender reputation. Web hooks in SES Monitor provide a proactive and efficient way to stay informed about your email performance and address potential issues as they arise.

Creating AWS SES Web Hooks

From within your SES Monitor account navigate to the "Integrations" section where you'll see an option for Web Hooks. Click the "Create New" button. Give it a suitable name (e.g. "Email Feedback") as well as the HTTP endpoint where you'd like the notifications to be sent. You can then choose which email events you'd like to receive inlcuding deliveries, bounces and complaints.

You can create as many SES web hooks as you like so you can use it to notify as many URLs as you need.

SES Web Hook Payload

Whenever one of the chosen event types is triggered our system will send a HTTP request to the URL provided. This will be a POST request with the body containing a JSON encoded array.

Depending on the type of event the payload will differ. Here's some example payloads for each of the three event types.

Delivery Web Hook Payload

Array
(
    [timestamp] => 1681235078
    [type] => delivery
    [brand] => Array
        (
            [uuid] => 1aac544c-491c-11eb-b383-8e819577b7b4
            [name] => My SES Monitor Account
        )

    [webhook] => Array
        (
            [uuid] => 64e9cd04-0e5b-11ed-95a5-ca77812a30dc
            [name] => SES Web Hook
        )

    [message] => Array
        (
            [uuid] => 7bf99312-d890-11ed-a507-4ed5cae9bdd1
            [mailerMessageId] => 01020187716ac5f4-2b0fbfb0-f17b-4356-849d-530703d13c04-000000
            [mailerTimestamp] => Array
                (
                    [date] => 2023-04-11 17:43:55.000000
                    [timezone_type] => 3
                    [timezone] => UTC
                )

            [mailerSourceARN] => arn:aws:ses:eu-west-1:XXXXXXXXXXXX:identity/sesmonitor.com
            [mailerSourceIP] => IP_REDACTED
            [headers] => Array
                (
                    [0] => Array
                        (
                            [uuid] => 7bf997ea-d890-11ed-9e9f-4ed5cae9bdd1
                            [name] => Date
                            [value] => Tue, 11 Apr 2023 17:43:55 +0000
                        )

                    [1] => Array
                        (
                            [uuid] => 7bf99862-d890-11ed-8179-4ed5cae9bdd1
                            [name] => Subject
                            [value] => SES Monitor is Awesome!
                        )

                    [2] => Array
                        (
                            [uuid] => 7bf998d0-d890-11ed-8c24-4ed5cae9bdd1
                            [name] => From
                            [value] => hello@sesmonitor.com
                        )

                    [3] => Array
                        (
                            [uuid] => 7bf9993e-d890-11ed-86fd-4ed5cae9bdd1
                            [name] => To
                            [value] => hello@sshbackups.com
                        )

                )

        )

    [deliveries] => Array
        (
            [0] => Array
                (
                    [uuid] => 7c2c2a8e-d890-11ed-ac3d-4ed5cae9bdd1
                    [recipient] => Array
                        (
                            [uuid] => c01744fc-bc1e-11ec-bce7-ca77812a30dc
                            [email] => hello@sshbackups.com
                        )

                    [mailerProcessingTimeMillis] => 4819
                    [mailerSmtpResponse] => 250 2.0.0 Ok: queued as 6E64A39C00A1
                    [mailerRemoteMtaIp] => IP_REDACTED
                    [mailerTimestamp] => 2023-04-11T17:44:00+00:00
                    [mailerReportingMTA] => a7-32.smtp-out.eu-west-1.amazonses.com
                )

        )

)

Bounce Web Hook Payload

Array
(
    [timestamp] => 1681235078
    [type] => bounce
    [brand] => Array
        (
            [uuid] => 1aac544c-491c-11eb-b383-8e819577b7b4
            [name] => My SES Monitor Account
        )

    [webhook] => Array
        (
            [uuid] => 64e9cd04-0e5b-11ed-95a5-ca77812a30dc
            [name] => SES Web Hook
        )

    [message] => Array
        (
            [uuid] => 7bf99312-d890-11ed-a507-4ed5cae9bdd1
            [mailerMessageId] => 01020187716ac5f4-2b0fbfb0-f17b-4356-849d-530703d13c04-000000
            [mailerTimestamp] => Array
                (
                    [date] => 2023-04-11 17:43:55.000000
                    [timezone_type] => 3
                    [timezone] => UTC
                )

            [mailerSourceARN] => arn:aws:ses:eu-west-1:XXXXXXXXXXXX:identity/sesmonitor.com
            [mailerSourceIP] => IP_REDACTED
            [headers] => Array
                (
                    [0] => Array
                        (
                            [uuid] => 7bf997ea-d890-11ed-9e9f-4ed5cae9bdd1
                            [name] => Date
                            [value] => Tue, 11 Apr 2023 17:43:55 +0000
                        )

                    [1] => Array
                        (
                            [uuid] => 7bf99862-d890-11ed-8179-4ed5cae9bdd1
                            [name] => Subject
                            [value] => SES Monitor is Awesome!
                        )

                    [2] => Array
                        (
                            [uuid] => 7bf998d0-d890-11ed-8c24-4ed5cae9bdd1
                            [name] => From
                            [value] => hello@sesmonitor.com
                        )

                    [3] => Array
                        (
                            [uuid] => 7bf9993e-d890-11ed-86fd-4ed5cae9bdd1
                            [name] => To
                            [value] => hello@sshbackups.com
                        )

                )

        )

    [bounces] => Array
        (
            [0] => Array
                (
                    [uuid] => 7c2c2a8e-d890-11ed-ac3d-4ed5cae9bdd1
                    [recipient] => Array
                        (
                            [uuid] => c01744fc-bc1e-11ec-bce7-ca77812a30dc
                            [email] => hello@sshbackups.com
                        )
                    [mailerFeedbackId] => 010201877192109d-7fd23d57-ce8d-4551-a592-8f4602ba88db-000000
                    [mailerBounceType] => Permanent
                    [mailerBounceSubType] => General
                    [mailerRemoteMtaIp] => IP_REDACTED
                    [mailerReportingMTA] => dns; a7-32.smtp-out.eu-west-1.amazonses.com
                    [mailerTimestamp] => 2023-04-11T18:26:50+00:00
                    [mailerAction] => failed
                    [mailerStatus] => 5.1.1
                    [mailerDiagnosticCode] => smtp; 550-5.1.1
                )

        )

)

Complaint Web Hook Payload

Array
(
    [timestamp] => 1681235078
    [type] => complaint
    [brand] => Array
        (
            [uuid] => 1aac544c-491c-11eb-b383-8e819577b7b4
            [name] => My SES Monitor Account
        )

    [webhook] => Array
        (
            [uuid] => 64e9cd04-0e5b-11ed-95a5-ca77812a30dc
            [name] => SES Web Hook
        )

    [message] => Array
        (
            [uuid] => 7bf99312-d890-11ed-a507-4ed5cae9bdd1
            [mailerMessageId] => 01020187716ac5f4-2b0fbfb0-f17b-4356-849d-530703d13c04-000000
            [mailerTimestamp] => Array
                (
                    [date] => 2023-04-11 17:43:55.000000
                    [timezone_type] => 3
                    [timezone] => UTC
                )

            [mailerSourceARN] => arn:aws:ses:eu-west-1:XXXXXXXXXXXX:identity/sesmonitor.com
            [mailerSourceIP] => IP_REDACTED
            [headers] => Array
                (
                    [0] => Array
                        (
                            [uuid] => 7bf997ea-d890-11ed-9e9f-4ed5cae9bdd1
                            [name] => Date
                            [value] => Tue, 11 Apr 2023 17:43:55 +0000
                        )

                    [1] => Array
                        (
                            [uuid] => 7bf99862-d890-11ed-8179-4ed5cae9bdd1
                            [name] => Subject
                            [value] => SES Monitor is Awesome!
                        )

                    [2] => Array
                        (
                            [uuid] => 7bf998d0-d890-11ed-8c24-4ed5cae9bdd1
                            [name] => From
                            [value] => hello@sesmonitor.com
                        )

                    [3] => Array
                        (
                            [uuid] => 7bf9993e-d890-11ed-86fd-4ed5cae9bdd1
                            [name] => To
                            [value] => hello@sshbackups.com
                        )

                )

        )

    [complaints] => Array
        (
            [0] => Array
                (
                    [uuid] => 7c2c2a8e-d890-11ed-ac3d-4ed5cae9bdd1
                    [recipient] => Array
                        (
                            [uuid] => c01744fc-bc1e-11ec-bce7-ca77812a30dc
                            [email] => hello@sshbackups.com
                        )
                    [mailerFeedbackId] => 010201877192109d-7fd23d57-ce8d-4551-a592-8f4602ba88db-000000
                    [mailerTimestamp] => 2023-04-11T18:26:50+00:00
                    [mailerUserAgent] => ExampleCorp Feedback Loop (V0.01)
                    [mailerComplaintFeedbackType] => abuse
                    [mailerArrivalDate] => 2023-04-11T18:26:50+00:00
                )

        )

)

IP Whitelisting

A completely optional step would be to whitelist our IP address. This can help to ensure you know where these notifications are coming from, only allowing our systems to connect to your web hook URL. If you want to do this you should whitelist "138.68.191.189".