how to debug lobstermail webhooks locally with ngrok replay

Something breaks in your webhook handler. You don't know if it's the HMAC verification, the payload parsing, or something in between. Your agent is silently dropping emails. The only way to reproduce it is to send another email, wait, check logs, realize you're missing a header, and start over.

There's a better loop.

This guide covers local webhook debugging for LobsterMail end-to-end: ngrok tunnel setup, signature verification (where most handlers quietly fail), and the replay button that will save you a few hours of "send another test email" cycles.

Why webhooks need a real debugging setup#

Polling is forgiving. If your polling handler crashes, you just poll again on the next interval. Webhooks are not. The delivery attempt happens, your server returns a non-2xx status, and LobsterMail queues a retry. After 10 consecutive failures, the webhook is automatically disabled.

That failure mode is invisible unless you're watching logs in real time. And it's hard to reproduce locally without either a public tunnel or a lot of manual curl commands.

If you're still deciding whether webhooks are even right for your setup, webhooks vs. polling for agent email covers the tradeoffs. For agents that need low-latency email handling, webhooks are almost always the right call. The debugging setup is a small one-time investment.

The right local setup gives you three things:

• A stable public HTTPS URL that forwards to your localhost
• Full request inspection (headers, body, timing) without touching production code
• One-click replay so you can trigger the same payload as many times as you need while you iterate

Step 1: Get ngrok running#

Install ngrok, start your local server on whatever port you're using — let's say 3000 — and expose it:

ngrok http 3000

ngrok prints two forwarding URLs. Use the https:// one. It'll look something like https://abc123.ngrok-free.app. Copy it.

Then open http://localhost:4040 in a browser tab. That's ngrok's web inspector. Keep it open. You'll live in that tab for the rest of this session.

Step 2: Register the webhook#

Point LobsterMail at your ngrok URL. The path is whatever your handler listens on:

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();

const webhook = await lm.createWebhook({
  url: 'https://abc123.ngrok-free.app/hooks/lobstermail',
  events: ['email.received'],
});

console.log(webhook.secret); // whsec_... — store this immediately

The secret is returned only once. Put it in your .env now. If you lose it, you'll need to delete and recreate the webhook — which is annoying but not catastrophic.

Step 3: Verify the signature (and the order that matters)#

This is where most webhook handlers fail silently. Every request from LobsterMail includes an X-LobsterMail-Signature header: an HMAC-SHA256 signature computed over the raw request body. If you parse the body before verifying — which most Express middleware does automatically — the verification will fail because the bytes have already changed shape.

Here's a working handler:

import { createHmac } from 'node:crypto';
import express from 'express';

const app = express();

// express.raw() on this route, NOT express.json()
app.post('/hooks/lobstermail', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-lobstermail-signature'] as string;
  const secret = process.env.LOBSTERMAIL_WEBHOOK_SECRET!;

  const expected = createHmac('sha256', secret)
    .update(req.body) // Buffer, not a parsed object
    .digest('hex');

  if (expected !== signature) {
    console.error('Signature mismatch');
    res.status(401).send('Unauthorized');
    return;
  }

  const payload = JSON.parse(req.body.toString());
  console.log('Event:', payload.event);
  console.log('Email ID:', payload.data.emailId);
  console.log('From:', payload.data.from);

  res.status(200).send('OK');
});

app.listen(3000);

The specific failure mode worth understanding: if you use express.json() on the webhook route, req.body becomes a JavaScript object. The HMAC you compute over that object's serialized form won't match the signature computed over the original raw bytes. Your server returns 401. LobsterMail retries with exponential backoff. After 10 retries, it disables the webhook. You spend the next hour wondering why your agent stopped responding to emails.

Raw body first, then verify, then parse. That order is load-bearing.

Step 4: Trigger a real delivery#

Send a test email to one of your agent's inboxes. You can do this via the SDK, or just send an email directly to whatever address your agent provisioned.

Switch to localhost:4040. The request appears in real time: status code, every header, full body, response time. If your handler returned 200, great. If it returned 401, you can see exactly what came in and start debugging against the real payload.

Step 5: Use the replay button#

This is the part that makes the whole setup worth it. In the ngrok inspector, find the request and click Replay. ngrok resends the exact same HTTP request — same headers, same body, same signature — to your local server.

Now your loop is:

1. Fix a bug in your handler
2. Click replay
3. Check the response
4. Repeat

No sending another email each time. No waiting for an external event. Same payload, over and over, until the handler works.

There's also Replay with modifications, which lets you edit the JSON before resending. Useful for testing edge cases: what happens if emailId is missing? What if event is an unexpected type? You can manufacture those cases without any code changes on the LobsterMail side.

One practical note: the free ngrok tier assigns a new random URL every time you restart it. That means re-registering your webhook each session. Some alternatives (Thunderhooks, Pinggy) offer stable persistent URLs that don't change between restarts, which removes that friction for longer debugging runs.

What happens when things fail#

If your local server isn't running — or ngrok isn't — LobsterMail will see a connection refused and start the retry sequence. That's expected during development. Just re-enable the webhook when you're back:

PATCH /v1/webhooks/:id
{ "enabled": true }

Or check what's currently registered:

const webhooks = await lm.listWebhooks();

The retry window is up to 10 attempts with exponential backoff, so you have time to get your server back up without losing the delivery. For a sandbox inbox where you're doing repeated integration testing, the agent email sandbox guide covers how to set up isolated inboxes so multiple developers aren't stepping on each other's test payloads.

The full loop, condensed#

1. Start your local handler
2. Start ngrok, grab the HTTPS URL
3. Register (or update) your LobsterMail webhook with that URL
4. Trigger one real email to get the first payload into ngrok's inspector
5. Fix bugs, replay, fix bugs, replay
6. When the handler is working, deploy and update the webhook URL to your production endpoint

The replay step at 5 is what collapses a 2-hour debugging session into 20 minutes.

Give your agent its own inbox. Get started with LobsterMail — free, no credit card.