webhook-relay skill

# webhook-relay skill

## When to use

Use this skill when the user wants to:

- Receive webhooks from external services (GitHub, Stripe, Shopify, etc.) during local development
- Forward inbound webhooks to one or more local HTTP services simultaneously
- Inspect webhook payloads, headers, and forward attempt results in real time
- Replay a stored webhook to a local target without triggering the original event
- Manage forwarding targets from the CLI or dashboard

## Prerequisites

- Node.js 20+
- ngrok account and auth token (free tier is sufficient) - get one at ngrok.com
- Local service running and accepting HTTP requests

## Quick start

```
RELAY_NGROK_AUTHTOKEN=your_token npx webhook-relay
```

Dashboard: http://127.0.0.1:7701/dashboard
Webhook endpoint: https://<random>.ngrok-free.app/webhook

## CLI reference

| Command | Description |
|---------|-------------|
| `webhook-relay` | Start the relay server and open the dashboard |
| `webhook-relay targets add <url>` | Add a forwarding target |
| `webhook-relay targets list` | List all forwarding targets |
| `webhook-relay targets remove <name>` | Remove a target by name |
| `webhook-relay targets enable <name>` | Enable a disabled target |
| `webhook-relay targets disable <name>` | Disable a target without removing it |
| `webhook-relay list` | List recent webhooks |
| `webhook-relay show <id>` | Show full detail for a webhook |
| `webhook-relay replay <id>` | Re-send a stored webhook to all enabled targets |
| `webhook-relay status` | Show server, tunnel, and target status |

## Flags - start server

| Flag | Default | Description |
|------|---------|-------------|
| `--port` | `7701` | Local HTTP server port |
| `--no-open` | - | Do not open dashboard in browser on start |
| `--tunnel-provider` | `ngrok` | Tunnel provider: `ngrok`, `cloudflare`, `none` |

## Flags - targets add

| Flag | Default | Description |
|------|---------|-------------|
| `--name` | derived from URL | Label for the target |
| `--disabled` | - | Add target in disabled state |

## Flags - list

| Flag | Default | Description |
|------|---------|-------------|
| `--limit` | `50` | Maximum number of results to show |
| `--method` | all | Filter by HTTP method (GET, POST, PUT, etc.) |
| `--path` | all | Filter by path substring |

## Flags - show

| Flag | Default | Description |
|------|---------|-------------|
| `--body` | - | Print the raw body to stdout |
| `--headers` | - | Print all headers to stdout |

## Flags - replay

| Flag | Default | Description |
|------|---------|-------------|
| `--target` | all enabled | Only replay to a specific target by name |

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `RELAY_PORT` | `7701` | Local HTTP server port |
| `RELAY_PATH_PREFIX` | `/webhook` | URL path prefix for inbound webhooks |
| `RELAY_NGROK_AUTHTOKEN` | - | ngrok auth token. Required for ngrok tunneling |
| `RELAY_TUNNEL_PROVIDER` | `ngrok` | Tunnel provider: `ngrok`, `cloudflare`, `none` |
| `RELAY_MAX_STORED` | `1000` | Maximum number of webhooks kept in the ring buffer |
| `RELAY_MAX_BODY_BYTES` | `1048576` | Bodies larger than this are truncated (1MB) |
| `RELAY_FORWARD_TIMEOUT_MS` | `5000` | Per-target forward request timeout in milliseconds |
| `RELAY_LOG_BODIES` | `0` | Log webhook bodies to stdout. Set to `1` to enable |
| `RELAY_DATA_DIR` | `~/.webhook-relay` | Directory for the SQLite database |

## Forwarding behavior

- Every inbound webhook is forwarded to all enabled targets simultaneously.
- The relay always returns `200 OK` to the sender immediately, regardless of forward results.
- Failed forwards (timeout, 5xx, connection error) are recorded and visible in the webhook detail.
- The `x-webhook-relay-id` header is added to every forward request.
- The original body is forwarded verbatim as a BLOB - no re-encoding.
- Headers are forwarded with lowercase names. `host`, `connection`, and `transfer-encoding` are removed.

## Ring buffer

The webhook store is a ring buffer capped at `RELAY_MAX_STORED` entries. When the limit is reached, the oldest webhook and its forward attempt records are deleted before the new one is inserted. This keeps storage bounded without manual cleanup.

## Storage location

SQLite database at `~/.webhook-relay/data.db` (or `RELAY_DATA_DIR/data.db`). The database is created automatically on first run.

## Replay semantics

Replaying a webhook re-sends the original body and headers (minus `host`, `connection`, `transfer-encoding`) to all enabled targets. A new set of forward attempt records is created and linked to the original webhook. The original webhook record is not modified.

## Troubleshooting

| Symptom | Resolution |
|---------|------------|
| Tunnel not starting | Check `RELAY_NGROK_AUTHTOKEN` is set and valid. Run `webhook-relay status` to see the error message |
| Webhook received but 0 forwards | All targets may be disabled. Run `webhook-relay targets list` to check |
| Forward always timing out | The local target is not running or the port is wrong. Verify with `curl <target-url>` |
| Port 7701 already in use | Set `RELAY_PORT` to a different value or stop the conflicting process |
| Body shows as `[truncated]` | Body exceeded `RELAY_MAX_BODY_BYTES`. Increase the limit or check the sender payload size |
| Old webhooks disappearing | The ring buffer is full. Increase `RELAY_MAX_STORED` to retain more history |