Listen

The listen command streams webhook events in real time. You can create an anonymous ephemeral channel, subscribe to an app or source, and optionally forward events to a local HTTP endpoint.

Anonymous Mode

Without --app-id or --source-id (and with no app or source in hookie.yml), hookie listen creates an anonymous ephemeral channel. This happens even when you are logged in.

hookie listen

You get a temporary webhook URL (for example https://ingest.hookie.sh/a/brave-falcon-k7m2xp) with a time limit and rate limits. Useful for quick tests before you wire up a permanent app.

If you are logged in, the CLI tips you to pass --app-id / --source-id (or use hookie.yml) for your registered sources.

Example Output

╔═══════════════════════════════════════════════════════════╗
║  Anonymous Ephemeral Channel Created                      ║
╠═══════════════════════════════════════════════════════════╣
║  Webhook URL: https://ingest.hookie.sh/a/brave-falcon-k7m2xp      ║
║  Expires in: 24 hours                                     ║
║  Rate limits: 100/min, 10000/day, 100 KB payload          ║
╚═══════════════════════════════════════════════════════════╝

Limits and expiry come from the server response; treat the banner values as authoritative.

To stream events for a registered app or source, pass --app-id (application public id). Add --source-id (source slug) to subscribe to one source. You can also set these in hookie.yml. You must be logged in.

App Subscription

Subscribe to all sources of an application with --app-id (or -a):

hookie listen --app-id <app-public-id>

Example:

hookie listen --app-id billing-api-k7m2xp

Source Subscription

Subscribe to a specific source with --app-id and --source-id (or -s):

hookie listen --app-id <app-public-id> --source-id <source-slug>

Example:

hookie listen --app-id billing-api-k7m2xp --source-id stripe

--source-id requires --app-id.

Flags

--app-id or -a — Subscribe to all sources of an application
--source-id or -s — Subscribe to a specific source
--forward-to or -f — Forward events to an endpoint URL (--forward is an alias)
--ui — Show the local UI when forwarding with --forward-to (UI is on by default when you are not forwarding)
--org-id — Organization ID (for org-owned applications)
--debug or -d — Show headers, query params, body, and related detail

Local UI

By default, hookie listen starts a local UI (default port 4840, override with HOOKIE_UI_PORT) and opens it in your browser:

hookie listen

When you pass --forward-to, the UI is off unless you also pass --ui:

hookie listen --app-id billing-api-k7m2xp --forward-to http://localhost:3001/webhooks --ui

The first instance starts the GUI and opens the browser. Later instances reuse the existing GUI without opening another window.

Event Display

Each event shows:

Timestamp — When the event occurred (RFC3339)
Application ID — The application that received the webhook
HTTP Method — GET, POST, and so on
Path — The webhook path
Source — The source the event belongs to (when applicable)

Organization-Owned Applications

For org-owned applications, pass the organization ID:

hookie listen --app-id <app-id> --org-id <org-id>

Or set it globally:

hookie --org-id <org-id> listen --app-id <app-id>

Debug Mode

hookie listen --app-id <app-id> --debug

Short form:

hookie listen --app-id <app-id> -d

Debug Output Example

2024-01-15T10:30:45Z [billing-api-k7m2xp] POST /webhooks/payment (source: stripe)
  Headers:
    Content-Type: application/json
    User-Agent: Stripe/1.0
    X-Request-ID: req_abc123
  Query:
    version: 2023-10-16
  Body:
    {
      "id": "evt_123",
      "type": "payment_intent.succeeded",
      "data": {
        "object": {
          "amount": 2000,
          "currency": "usd"
        }
      }
    }

Forward Events to a Local Endpoint

# Forward events from an application
hookie listen --app-id <app-id> --forward-to <endpoint-url>

# Forward events from a specific source
hookie listen --app-id <app-public-id> --source-id <source-slug> --forward-to <endpoint-url>

Example

# Forward events from an application
hookie listen --app-id billing-api-k7m2xp --forward-to http://localhost:3001/webhooks

# Shorthand
hookie listen --app-id billing-api-k7m2xp -f http://localhost:3001/webhooks

# Forward events from a specific source (requires app id)
hookie listen --app-id billing-api-k7m2xp --source-id stripe --forward-to http://localhost:3001/webhooks

The CLI:

Receives events from the relay
Prints them in the console
Forwards them to your endpoint with the original HTTP method, headers, query parameters, and body

Forwarding Output

2024-01-15T10:30:45Z [billing-api-k7m2xp] POST /webhooks/payment (source: stripe)
  → forwarded to http://localhost:3001/webhooks?version=2023-10-16 (status: 200)

On failure:

2024-01-15T10:30:45Z [billing-api-k7m2xp] POST /webhooks/payment (source: stripe)
  ✗ failed to forward: connection refused

Endpoint URL Requirements

The endpoint URL must include a scheme and host:

Valid: http://localhost:3001/webhooks
Valid: https://example.com/api/webhooks
Invalid: localhost:3001 (missing scheme)
Invalid: /webhooks (missing scheme and host)

Multiple Listeners

You can run multiple listeners in separate terminals:

# Terminal 1: all sources for billing-api-k7m2xp
hookie listen --app-id billing-api-k7m2xp

# Terminal 2: one source only
hookie listen --app-id billing-api-k7m2xp --source-id stripe

# Terminal 3: a different application
hookie listen --app-id checkout-api-m2n8xp

Stopping the Listener

Press Ctrl+C to stop. The CLI shuts down the stream and exits.

Event Forwarding Details

When forwarding, the CLI:

Preserves HTTP method — Original method (GET, POST, and so on)
Preserves headers — All headers except Host (set automatically)
Preserves query parameters — Appended to the endpoint URL
Preserves body — Original request body
Sets Content-Type — From the event when available
10-second timeout — Forward HTTP requests time out after 10 seconds

Forwarding is asynchronous, so it does not block receiving new events.

Authentication Errors

App and source subscriptions require login. Without a token:

Error: not authenticated. Run 'hookie login' first

Run hookie login, then retry. If the relay looks unhealthy, check with hookie status.

Repository Configuration

A hookie.yml file can supply app_id, source_id, forward, and per-source forward URLs so you can run hookie listen without flags.

See Configuration.

Configuration — hookie.yml and env vars
Applications — Find application IDs
Sources — Find source IDs
Status — Relay and auth health
Authentication — Manage your CLI session