Webhooks

SES publishes every lifecycle event to an SNS topic, which POSTs to /api/webhooks/ses. Mailgrid then writes to D1 and updates suppressions.

Webhook endpoint

Authentication: SNS signature verification (no Bearer token).

Setup

1. In SES console: Configuration sets → Create (e.g. inboxos-prod).
2. Open the set → Event destinations → Add destination.
3. Event types: tick Send, Delivery, Bounce, Complaint, Open, Click, Reject, Rendering failure, Delivery delay.
4. Destination: Amazon SNS → Create new topic (e.g. mailgrid-events).
5. Open the SNS topic → Create subscription:
   • Protocol: HTTPS
   • Endpoint: https://api.mailgrid.space/api/webhooks/ses
6. SNS posts a confirmation message; the Mailgrid endpoint auto-confirms it.

What happens when an event arrives

1. SNS posts the event JSON to the webhook.
2. Mailgrid verifies the SNS signature (against AWS's signing cert).
3. The payload is enqueued into a Cloudflare Queue.
4. Webhook returns 200 OK immediately.
5. Queue consumer parses the SNS payload and writes an event row to D1.
6. If the event is Bounce or Complaint, the recipient is added to suppressions.
7. On consumer failure, the message goes to the DLQ (inboxos-webhooks-dlq) after 5 retries.

SNS event types we handle