Listen

The listen command streams webhook events in real time from your relay. You can use anonymous mode against your ingest, pick an app or topic interactively, or subscribe with flags. Events can be forwarded to a local HTTP endpoint.

Anonymous Mode

Anonymous mode is only available when you're not authenticated. If you're logged in, use your existing applications and topics instead.

If you're not authenticated, hookie listen creates an anonymous ephemeral channel:

hookie listen

This creates a temporary webhook URL that expires after a set time. Perfect for quick testing without signing up.

Example Output

╔═══════════════════════════════════════════════════════════╗
║  Anonymous Ephemeral Channel Created                      ║
╠═══════════════════════════════════════════════════════════╣
║  Webhook URL: https://YOUR_INGEST_HOST/anon/anon_xxx     ║
║  Expires in: 24 hours                                    ║
║  Rate limits: 100/min, 10000/day, 100 KB payload         ║
╚═══════════════════════════════════════════════════════════╝

Authenticated Mode

When authenticated, hookie listen offers three ways to subscribe:

1. Interactive Selection

Run hookie listen without flags to see an interactive selector:

hookie listen

You'll see a list of both applications and topics. Select one:

App: Subscribes to all topics in that application
Topic: Subscribes to that specific topic only

2. Direct App Subscription

Subscribe to all topics of an application using --app-id (or -a):

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

Example

hookie listen --app-id app_123

Example Output

Listening for events (app: app_123, all topics)...
Press Ctrl+C to stop

2024-01-15T10:30:45Z [app_123] POST /webhooks/payment (topic: payments)
2024-01-15T10:30:46Z [app_123] GET /webhooks/status (topic: health)
2024-01-15T10:30:47Z [app_123] POST /webhooks/subscription (topic: subscriptions)

3. Direct Topic Subscription

Subscribe to a specific topic using --topic-id (or -t):

hookie listen --topic-id <topic-id>

Example

hookie listen --topic-id payments

Example Output

Listening for events (topic: payments)...
Press Ctrl+C to stop

2024-01-15T10:30:45Z [app_123] POST /webhooks/payment (topic: payments)
2024-01-15T10:30:48Z [app_123] POST /webhooks/payment (topic: payments)

Flags

--app-id or -a - Subscribe to all topics of an application
--topic-id or -t - Subscribe to a specific topic
--forward or -f - Forward events to a local endpoint URL
--ui - Show local UI when using --forward (UI is shown by default when not forwarding)
--org-id - Organization ID (for org-owned applications)
--debug or -d - Show detailed information (headers, query params, body)

Note: --app-id and --topic-id are mutually exclusive. You cannot specify both.

Local UI

By default, hookie listen starts a local UI in your browser where you can view incoming webhook events:

hookie listen

When forwarding with --forward, the UI is disabled by default. Add --ui to show the UI while forwarding:

hookie listen --app-id app_123 --forward http://localhost:3001/webhooks --ui

The browser opens automatically when the first instance starts the GUI. Subsequent instances reuse the existing GUI without opening a new browser window.

Event Display

Each event shows:

Timestamp - When the event occurred (RFC3339 format)
Application ID - The application that received the webhook
HTTP Method - The HTTP method (GET, POST, etc.)
Path - The webhook path
Topic - The topic the event belongs to (if applicable)

Organization-Owned Applications

For applications owned by an organization, specify the organization ID:

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

You can also set the organization ID globally:

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

Debug Mode

Enable detailed output including headers, query parameters, and request body:

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

Or use the short form:

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

Debug Output Example

2024-01-15T10:30:45Z [app_123] POST /webhooks/payment (topic: payments)
  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 Local Endpoint

Forward received events to a local HTTP endpoint using the --forward flag (or -f shorthand):

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

# Forward events from a specific topic
hookie listen --topic-id <topic-id> --forward <endpoint-url>

Example

# Forward all events from an application
hookie listen --app-id app_123 --forward http://localhost:3001/webhooks

# Or use the shorthand
hookie listen --app-id app_123 -f http://localhost:3001/webhooks

# Forward events from a specific topic
hookie listen --topic-id topic_456 --forward http://localhost:3001/webhooks

The CLI will:

Receive events from the relay
Display them in the console
Forward them to your local endpoint using the original HTTP method, headers, query parameters, and body

Forwarding Output

When forwarding is enabled, you'll see additional output:

2024-01-15T10:30:45Z [app_123] POST /webhooks/payment (topic: payments)
  → forwarded to http://localhost:3001/webhooks?version=2023-10-16 (status: 200)

If forwarding fails, you'll see an error:

2024-01-15T10:30:45Z [app_123] POST /webhooks/payment (topic: payments)
  ✗ failed to forward: connection refused

Endpoint URL Requirements

The endpoint URL must:

Include a scheme (http:// or https://)
Include a host (e.g., localhost:3001)
Be a valid URL

Examples:

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

Multiple Listeners

You can run multiple listeners simultaneously in separate terminals:

# Terminal 1: Listen to all topics for app_123
hookie listen --app-id app_123

# Terminal 2: Listen to payments topic only
hookie listen --topic-id payments

# Terminal 3: Listen to a different application
hookie listen --app-id app_456

Stopping the Listener

Press Ctrl+C to stop listening. The CLI will gracefully shut down:

^C
Shutting down...

Event Forwarding Details

When forwarding events, the CLI:

Preserves HTTP method - Uses the original method (GET, POST, etc.)
Preserves headers - Forwards all headers except Host (set automatically)
Preserves query parameters - Adds query parameters from the event to the endpoint URL
Preserves body - Forwards the original request body
Sets Content-Type - Uses the event's Content-Type header if available
10-second timeout - HTTP requests timeout after 10 seconds

Forwarding happens asynchronously, so it won't block receiving new events.

Authentication

For authenticated features (app/topic subscriptions), you must be logged in. If you're not authenticated, you'll see:

Error: not authenticated. Run 'hookie login' first

Run hookie login to authenticate.

Common Use Cases

Local development - Stream events to your development environment
Quick testing - Use anonymous mode for temporary webhook URLs
Debugging - Use debug mode to inspect webhook payloads
Testing - Forward events to local test servers
Monitoring - Watch events in real-time across multiple applications
Topic filtering - Focus on specific event types

Repository Configuration

You can use a hookie.yml file in your repository to configure app_id, forward URLs, and per-topic forwarding. This allows you to run hookie listen without specifying flags.

See the Configuration documentation for details on setting up repository configuration.

Configuration - Set up repository configuration with hookie.yml
Applications - Find application IDs
Topics - Find topic IDs for filtering
Authentication - Manage your CLI session

Listen

On this page