Webhooks

Receive real-time notifications when emails arrive, bounce, or are delivered.

Last updated 2026-02-23

Why webhooks#

Polling for new messages works, but webhooks are faster and more efficient. Instead of checking every few seconds, LobsterMail sends an HTTP POST to your server the moment something happens.

Create a webhook#

const webhook = await lobster.webhook.create({
  inboxId: inbox.id,
  url: "https://your-server.com/webhook/lobstermail",
  events: ["message.received"],
});

Webhook events#

| Event | Fired when | |-------|------------| | message.received | A new email arrives in the inbox | | message.sent | An outbound email is successfully sent | | message.bounced | An outbound email bounces | | message.delivered | An outbound email is delivered |

You can subscribe to multiple events at once:

await lobster.webhook.create({
  inboxId: inbox.id,
  url: "https://your-server.com/webhook/lobstermail",
  events: ["message.received", "message.bounced"],
});

Webhook payload#

When an event fires, LobsterMail sends a POST request with this JSON body:

{
  "event": "message.received",
  "timestamp": "2026-02-23T12:00:00Z",
  "inboxId": "inbox_abc123",
  "data": {
    "messageId": "msg_def456",
    "from": "alice@example.com",
    "to": "clawbot-7x2k@lobstermail.ai",
    "subject": "Hello there",
    "preview": "Just wanted to say hi..."
  }
}

Verify webhook signatures#

Every webhook request includes a X-LobsterMail-Signature header. Verify it to ensure the request came from LobsterMail:

import { LobsterMail } from "lobstermail";

const isValid = LobsterMail.verifyWebhookSignature({
  payload: requestBody,
  signature: request.headers["x-lobstermail-signature"],
  secret: webhook.secret,
});

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}

Retry policy#

If your server returns a non-2xx status code, LobsterMail retries with exponential backoff:

  • 1st retry: 30 seconds
  • 2nd retry: 2 minutes
  • 3rd retry: 10 minutes
  • 4th retry: 1 hour
  • 5th retry: 6 hours (final attempt)

After 5 failed attempts, the webhook is disabled and you'll receive an email notification.

List and manage webhooks#

// List all webhooks for an inbox
const webhooks = await lobster.webhook.list(inbox.id);

// Delete a webhook
await lobster.webhook.delete(webhook.id);

What's next#