> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Delivery Failures

> Diagnose and fix webhook delivery issues, including retry logic, timeout handling, debugging failed deliveries, and endpoint authentication.

Lettr sends webhook events to your server when email events occur (delivery, bounce, open, click, complaint, etc.). When your endpoint fails to receive or process these events, you lose visibility into your email delivery pipeline. This guide covers how to diagnose and fix webhook delivery failures.

***

## How Lettr Webhook Delivery Works

When an email event occurs, Lettr sends an HTTP POST request to your configured webhook endpoint. The delivery follows this sequence:

1. Event occurs (e.g., email is delivered)
2. Lettr queues the webhook payload
3. Lettr sends an HTTP POST to your endpoint URL
4. Your server must respond with a `2xx` status code within **30 seconds**
5. If the request fails, Lettr retries with exponential backoff

### What Counts as a Failure

| Response | Result |
| - | - |
| `2xx` status code | Success: event is marked as delivered |
| `3xx` redirect | Failure: Lettr does not follow redirects |
| `410` status code | Failure: not retried; the webhook is disabled |
| Other `4xx` status code | Failure: retried according to retry schedule |
| `5xx` status code | Failure: retried according to retry schedule |
| Connection timeout (30s) | Failure: retried according to retry schedule |
| DNS resolution failure | Failure: retried according to retry schedule |
| TLS handshake failure | Failure: retried according to retry schedule |

> [!WARNING]
>
> Lettr does not follow HTTP redirects (`301`, `302`, `307`, `308`). Your endpoint must respond directly with a `2xx` status. If your URL has changed, update it in the [Webhooks settings](https://app.lettr.com/webhooks).

***

## Retry Logic and Schedule

When a webhook delivery fails, Lettr retries the request with exponential backoff:

| Attempt | Delay After Previous Attempt |
| - | - |
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 30 minutes |
| 4th retry | 2 hours |
| 5th retry | 8 hours |
| 6th retry | 24 hours |

After 6 failed retries (7 total attempts, spanning roughly 35 hours), the webhook event is marked as **permanently failed** and no further delivery attempts are made. Webhooks that keep failing are disabled automatically; re-enable them from the webhook's page in the dashboard once the issue is fixed.

> [!NOTE]
>
> The webhook's page in the Lettr dashboard (**Webhooks**, then select the webhook) shows its **Last Attempt** time and **Last Status**. Failed events can't be replayed from the dashboard, so make your own system able to recover missed events.

***

## Diagnosing Failures

> [!TIP]
>
> A quick first pass: ask [Adamko](https://docs.lettr.com/learn/ai-assistant/troubleshooting-and-diagnostics.md#integration--api-problems) *"is my webhook working?"* — he reads your endpoint configuration and its last success and failure, alongside your recent API activity, and points at the most likely problem before you start digging through logs.

### Check the Webhook Status

Start with the webhook's status in the Lettr dashboard:

1. Go to **Webhooks** in the dashboard
2. Click on the webhook endpoint that is failing
3. Check whether it is **Enabled**, and review its **Last Attempt** and **Last Status**
4. Compare the last attempt time with your server and load balancer logs to see the request Lettr sent and the response your server returned

### Common Failure Patterns

> [accordion] All events failing with connection timeout
>
> Your server is taking longer than 30 seconds to respond.
>
> **Fixes:**
>
> * Process webhook events asynchronously. Accept the request immediately (return `200`), then process the event in a background job.
> * Check if your server is overloaded or if the webhook handler has a performance bottleneck.
> * Verify your firewall or WAF is not dropping or holding POST requests to your webhook path. Webhooks are not sent from a fixed, published set of IP addresses, so allow the path rather than specific IPs.

> [accordion] All events failing with DNS resolution error
>
> Lettr cannot resolve your webhook endpoint hostname.
>
> **Fixes:**
>
> * Verify the URL in your webhook settings is correct.
> * Check that your DNS records are properly configured and your domain is resolving.
> * If you recently changed DNS providers, wait for propagation to complete.

> [accordion] All events failing with TLS error
>
> The TLS handshake to your server is failing.
>
> **Fixes:**
>
> * Verify your SSL certificate is valid and not expired.
> * Ensure your server supports TLS 1.2 or higher.
> * Check that the certificate chain is complete (intermediate certificates included).
>
> ```bash theme={null}
> # Test your endpoint's TLS configuration
> openssl s_client -connect yourdomain.com:443 -servername yourdomain.com
> ```

> [accordion] Intermittent 5xx errors
>
> Your server is sometimes returning 500-series errors.
>
> **Fixes:**
>
> * Check your server logs around the time of the failed deliveries.
> * Look for out-of-memory errors, database connection pool exhaustion, or unhandled exceptions in your webhook handler.
> * Ensure your webhook handler is idempotent — it should handle receiving the same event more than once.

> [accordion] 403 Forbidden responses
>
> Your server is rejecting the request due to authentication or authorization rules.
>
> **Fixes:**
>
> * If you have IP-based access controls, exempt your webhook path from them. Webhooks are not sent from a fixed, published set of IP addresses, so authenticate requests with the auth method configured on the webhook instead.
> * If you require authentication headers, make sure the Basic or OAuth 2.0 credentials configured on the webhook match what your middleware expects. Lettr doesn't send a signature header.
> * Check for CSRF protection middleware intercepting the POST request.

***

## Handling Timeouts

The 30-second timeout is the most common cause of webhook failures. Your webhook handler should return a response as quickly as possible.

### Recommended Architecture

```javascript theme={null}
const express = require("express");
const app = express();

// Good: Accept immediately, process in background
app.post(
  "/webhooks/lettr",
  express.raw({ type: "application/json" }),
  (req, res) => {
    // Verify credentials first
    const isValid = verifyBasicAuth(req);
    if (!isValid) {
      return res.status(401).send("Invalid credentials");
    }

    // Parse and queue for background processing
    const events = JSON.parse(req.body); // Array of events
    queue.add("process-webhook", events);

    // Respond immediately
    res.status(200).send("OK");
  }
);

// Bad: Processing synchronously blocks the response
app.post("/webhooks/lettr-slow", express.json(), (req, res) => {
  // This might take 30+ seconds and cause a timeout
  updateDatabase(req.body);
  sendSlackNotification(req.body);
  updateAnalytics(req.body);

  res.status(200).send("OK");
});
```

> [!TIP]
>
> Use a background job queue (Bull, Sidekiq, Laravel Queues, etc.) to process webhook events. This ensures you respond within the timeout and can handle high event volumes without blocking.

***

## Endpoint Authentication

Lettr doesn't sign webhook payloads. Instead, each webhook has an authentication type (**None**, **Basic**, or **OAuth 2.0**), and Lettr sends the matching `Authorization` header with every request. Use Basic or OAuth 2.0 in production and reject requests without valid credentials.

### Verifying Basic Auth

1. Read the `Authorization` header
2. Decode the Base64 value after `Basic `
3. Compare the username and password with the ones configured on the webhook

```javascript theme={null}
const crypto = require("crypto");

function verifyBasicAuth(req) {
  const header = req.headers.authorization || "";
  if (!header.startsWith("Basic ")) return false;

  const expected = Buffer.from(
    `${process.env.LETTR_WEBHOOK_USERNAME}:${process.env.LETTR_WEBHOOK_PASSWORD}`
  ).toString("base64");
  const received = header.slice(6);

  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}
```

### Common Authentication Failures

| Problem | Cause | Fix |
| - | - | - |
| Header always empty | A proxy, CDN, or gateway strips the `Authorization` header | Configure it to pass the header through to your application |
| Looking for a signature | Expecting a `lettr-signature` or `x-signature` header | Lettr doesn't sign payloads; check the `Authorization` header instead |
| Wrong credentials | Using credentials from a different webhook | Each webhook has its own authentication settings; check the dashboard |
| OAuth 2.0 token rejected | Token URL, client ID, or client secret is wrong | Lettr fetches a token from your OAuth server before each delivery; confirm all three values |

> [!WARNING]
>
> Never run a production webhook without authentication. Without it, anyone who discovers your webhook URL can send forged events to your server.

***

## Idempotency

Lettr may deliver the same webhook event more than once (due to retries or network issues). Handlers must be idempotent: processing the same event twice should not cause duplicate side effects. See [Duplicate Emails](https://docs.lettr.com/knowledge-base/troubleshooting/duplicate-emails.md) for duplicate sends and webhook events.

### Implementing Idempotency

Use the `event_id` included in every event to deduplicate:

```javascript theme={null}
async function processWebhook(event) {
  const eventType = event.msys ? Object.keys(event.msys)[0] : null;
  const data = eventType ? event.msys[eventType] : null;
  if (!data) return;

  // Check if we've already processed this event
  const exists = await db.webhookEvents.findOne({ eventId: data.event_id });
  if (exists) {
    console.log(`Event ${data.event_id} already processed, skipping`);
    return;
  }

  // Process the event
  await handleEvent(data);

  // Record that we've processed it
  await db.webhookEvents.insertOne({
    eventId: data.event_id,
    processedAt: new Date(),
  });
}
```

***

## Testing Webhooks

Before deploying to production, test your webhook endpoint to verify it handles events correctly.

### Triggering Real Events

Generate real events by sending an email:

1. Go to **Webhooks**, select your endpoint, and confirm it is enabled and subscribed to the events you handle
2. Send an email with a live API key to an address you control
3. Open the email and click a link to generate engagement events
4. Check your server logs and the webhook's **Last Status** to verify delivery

### Using a Tunnel for Local Development

To test webhooks against a local development server, use a tunnel service:

```bash theme={null}
# Using ngrok
ngrok http 3000

# Using cloudflared
cloudflared tunnel --url http://localhost:3000
```

Copy the generated public URL and use it as your webhook endpoint in the Lettr dashboard. See [Webhook Testing](https://docs.lettr.com/learn/webhooks/testing.md) for more details.

***

## Related Topics

> [card] [Webhook Introduction](https://docs.lettr.com/learn/webhooks/introduction.md)
>
> Overview of Lettr's webhook system and available event types.

> [card] [Webhook Authorization](https://docs.lettr.com/learn/webhooks/authorization.md)
>
> Set up and verify webhook authentication.

> [card] [Webhook Retries](https://docs.lettr.com/learn/webhooks/retries.md)
>
> Detailed retry behavior and handling.

> [card] [Authentication Issues](https://docs.lettr.com/knowledge-base/troubleshooting/authentication.md)
>
> Troubleshoot API key and auth problems.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.