Skip to Content
ConceptsWebhooks

Webhooks

LobsterCage provides a gateway proxy that forwards HTTP webhooks to your cage. When your cage is hibernated, requests are buffered and delivered when it wakes.

Webhook URL

Each cage gets a stable webhook URL at creation:

https://gateway.lobstercage.ai/hook/{cageId}/{webhookToken}/{path}

This URL is injected into the cage as the LOBSTERCAGE_WEBHOOK_URL environment variable. Register it with any external service that sends webhooks.

Supported platforms

The gateway proxy works with any HTTP webhook sender. It has optimized response handling for:

  • Telegram — Bot API webhook updates
  • Slack — Event subscriptions and slash commands
  • Discord — Interaction endpoints
  • Signal — Signal Bot API
  • WhatsApp — WhatsApp Business API

How forwarding works

External service sends POST
        │
  Gateway proxy receives request
        │
  Cage running?
  ├─ Yes → Forward to cage immediately
  └─ No  → Buffer request, return 202, trigger wake
              │
        Cage wakes → health check → drain buffer in order

When the cage is running

Requests are forwarded directly to the cage’s internal IP on port 18789. The response from your application is returned to the caller.

When the cage is hibernated

  1. The request body is encrypted (AES-256-GCM) and stored in PostgreSQL
  2. A 202 Accepted response is returned immediately (platform-aware formatting)
  3. An async wake is triggered
  4. Once the cage passes health checks, buffered requests are drained in order

Buffered requests expire after 5 minutes.

Rate limits

The gateway proxy enforces rate limits to prevent abuse:

ScopeLimit
Per IP60 requests/min
Per cage30 requests/min

Rate limits are checked before reading the request body to prevent payload-based DoS.

Payload limits

Maximum webhook payload size: 1 MB (1,048,576 bytes).

Setting up a webhook

  1. Deploy a cage and note the webhook URL:

    lobster deploy my-bot
lobster status my-bot   # shows webhook URL

  2. Register the URL with your platform (e.g., Telegram setWebhook)

  3. Your application listens on port 18789 inside the cage

See the Telegram bot guide for a complete walkthrough.

BillingOverview