Copy page

Webhooks

Webhooks

Use webhooks to receive an HTTP POST request when a Lettermint event occurs. A webhook removes the need to poll the Team API for delivery updates.

When to use webhooks

Approach	How it works	Best for
Polling	Your server requests updates on a schedule.	Scheduled reports and occasional checks.
Webhooks	Lettermint sends each selected event to your endpoint.	Delivery handlers and event-driven workflows.

If your system processes bounce or complaint emails, use bounce and complaint forwarding. You can use forwarding and webhooks together.

Common use cases:

• Bounce handling: Remove invalid addresses from a mailing list.
• Delivery confirmation: Update your database after delivery.
• Engagement tracking: Start a workflow after a supported open or click.
• Complaint management: Stop email to recipients who report spam.
• Suppression synchronization: Copy suppression changes to another system.

Quick start

1. Create a webhook in the dashboard

1. Go to Dashboard → Webhooks.

2. Click Create webhook

3. Enter your webhook details:

   • Name: e.g., "Production Events"
   • URL: your HTTPS endpoint (e.g., https://api.example.com/webhooks/lettermint)
   • Scope: select all projects, one or more projects, or one or more routes
   • Events: select the event types you want to receive
   • Include machine events: off by default; enable it only if you want security scanner, preview, and generic bot tracking observations. Supported privacy opens do not need this option.
   • Enabled: keep on to start receiving events

4. Save. Your webhook is now active.

2. Send a test delivery

From the webhook details page, click Test Webhook. You should receive a payload like this:

Code
{
  "id": "test-7f9c8e2a-1b3d-4f6e-b7d2-5c9f3a7e8b0c",
  "event": "webhook.test",
  "timestamp": "2025-08-08T20:14:12.000Z",
  "context": {
    "scope": "team",
    "team_id": "9f4e3d2c-1b0a-4987-9654-3210fedcba98",
    "project_id": null,
    "route_id": null
  },
  "data": {
    "message": "This is a test webhook from Lettermint",
    "webhook_id": "9f9bf19c-4a2c-45f3-a6c7-bc937224ec5a",
    "timestamp": 1754921294
  }
}

Implementing a webhook endpoint

Here's a minimal endpoint that receives webhooks:

Best practices

Return 200 quickly Do heavy processing asynchronously. If your endpoint takes too long or returns an error, we'll retry the delivery.

Implement idempotency Use the event.id field to detect duplicate deliveries and prevent processing the same event twice:

Code
app.post('/webhooks/lettermint', async (req, res) => {
  const event = req.body

  // Check if we've already processed this event
  const alreadyProcessed = await db.webhookEvents.findUnique({
    where: { eventId: event.id }
  })

  if (alreadyProcessed) {
    return res.status(200).json({ received: true }) // Still return 200
  }

  // Process the event
  await handleEvent(event)

  // Mark as processed
  await db.webhookEvents.create({ data: { eventId: event.id } })

  res.status(200).json({ received: true })
})

HTTP headers

Every webhook delivery includes these headers:

Header	Description
X-Lettermint-Signature	HMAC-SHA256 signature for verification
X-Lettermint-Event	Event type (e.g., message.delivered)
X-Lettermint-Delivery	Delivery timestamp (Unix seconds)
X-Lettermint-Attempt	Retry attempt number (1, 2, 3...)

See Signed webhooks for details on verifying the signature.

Webhook fields

Field	Description
Name	Display name for your webhook
URL	HTTPS endpoint we POST to
Scope	All projects, selected projects, or selected routes that send events to the webhook
Events	Array of event types to receive
Include machine events	Whether message.opened and message.clicked webhooks include security scanner, preview, and generic bot observations. Supported privacy opens do not need this option. Disabled by default.
Enabled	Whether the webhook is active
Secret	HMAC secret for signature verification (rotatable)
Deliveries	Recent delivery attempts with status, response, and timing

Delivery and retries

We retry failed webhook deliveries with exponential backoff. A delivery fails if your endpoint returns a non-2xx status or times out (30 seconds).

Retry schedule (12 total attempts: 1 initial attempt + 11 automatic retries):

Attempt	Delay after previous
1	Immediate
2	1 minute
3	2 minutes
4	5 minutes
5	10 minutes
6	10 minutes
7	15 minutes
8	30 minutes
9	1 hour
10	2 hours
11	4 hours
12	6 hours

This schedule spans roughly 14 hours from the initial delivery attempt to the final automatic retry.

After all retries are exhausted, the delivery is marked as failed. You can see all delivery attempts in the dashboard by clicking on your webhook.

Troubleshooting

Webhook is disabled

Problem: No events are being delivered

Solution: Check that the webhook's Enabled toggle is on. Disabled webhooks won't send any deliveries.

No deliveries appear

Problem: Expected events aren't showing up

Solutions:

• Use the Test Webhook button to verify your endpoint is reachable
• Confirm your endpoint returns a 2xx status code
• Check your server logs for incoming requests
• Verify that the webhook scope includes the route and that the webhook uses the correct events

Repeated retries

Problem: The same event keeps being retried

Solutions:

• Your endpoint must return 200-299 status quickly (within 30 seconds)
• Move heavy processing to a background job and return 200 immediately
• Implement idempotency using event.id to handle duplicate deliveries gracefully

Connection refused or timeout

Problem: Deliveries fail with connection errors

Solutions:

• Ensure your endpoint is publicly accessible (not localhost)
• Check firewall rules allow incoming HTTPS connections
• Verify SSL/TLS certificate is valid and not expired
• For local development, use a tunnel like ngrok

Signature verification fails

Problem: All webhooks are rejected as invalid

Solution: See the troubleshooting section in Signed webhooks.

Next steps

• Signed webhooks: Verify webhook authenticity (required for production)
• Webhook events: See all available event types and their payloads