webhooks.yaml

Save your alias setup in a config file you can commit with the repo.

webhooks.yaml is a project-local config file that maps named aliases to subdomains and ports. It is the recommended way to use FixedHook in a team — commit the file with the repo and everyone runs the same tunnels with the same names.

Where the file lives

The CLI looks for webhooks.yaml in the current working directory by default. Use --config <path> to point it at a different location.

The shape

version: 1
 
aliases:
  - name: app
    subdomain: my-app-dev
    port: 3000
 
  - name: stripe
    subdomain: my-app-stripe
    port: 3000
 
  - name: api
    subdomain: my-app-api
    port: 4000

Field	Required	Description
`version`	Yes	Schema version. Currently `1`
`aliases`	Yes	List of named alias entries
`name`	Yes	Local handle, used as `fixedhook up <name>`
`subdomain`	Yes	Subdomain the alias is registered under
`port`	Yes	Local port the tunnel forwards to
`host`	No	Local host (defaults to `127.0.0.1`)
`displayName`	No	Friendly name shown in the dashboard

Generate one

fixedhook config init

The CLI writes a starter file with one entry. Edit it to match your project. Run fixedhook config validate to check for mistakes.

Run a named tunnel

Once the file is in place, you can run a tunnel by name:

fixedhook up app      # uses the "app" entry
fixedhook up stripe   # uses the "stripe" entry

The CLI:

Reads webhooks.yaml.
Looks up the entry by name.
Resolves the subdomain. If the alias does not exist on your account yet, the CLI creates it automatically.
Starts the tunnel against the configured port.

Aliases are claimed, not just configured

When you run fixedhook up stripe for the first time, FixedHook creates the my-app-stripe alias on your account if it doesn't exist. After that, the alias persists across machines, teammates, and CI runs.

Multi-alias workflows

A single project often has more than one provider to debug. A common pattern is one alias per provider:

version: 1
 
aliases:
  - name: stripe
    subdomain: acme-stripe
    port: 3000
  - name: github
    subdomain: acme-github
    port: 4000
  - name: shopify
    subdomain: acme-shopify
    port: 5000

You can run them all at once:

fixedhook up --all

Or one at a time. Each alias is an independent tunnel with its own online status and event stream.

Explicit flags override the file

CLI flags win over the config file. This is the recommended escape hatch for one-off changes:

fixedhook up stripe --port 3001

This runs the stripe alias entry but uses port 3001 instead of the configured one. The config file is unchanged.

Validating

fixedhook config validate

The CLI checks for:

Unknown or missing top-level fields.
Duplicate name or subdomain entries.
Subdomain naming rule violations.
Missing required fields per entry.
Invalid port values (must be an integer between 1 and 65535).

If validation fails, the command exits non-zero and prints the specific problem.

Versioning

The version field in the file is the schema version, not the CLI version. If the schema changes in a backward-incompatible way, the CLI will refuse to load the file and print a clear message. Today, the only valid value is 1.

Per-environment files

A common pattern is to keep one webhooks.yaml per branch or environment:

webhooks.yaml             # main branch / shared dev
webhooks.staging.yaml     # preview deployments
webhooks.production.yaml  # production tunnels

Switch between them with --config:

fixedhook up stripe --config webhooks.staging.yaml

You can ignore these in .gitignore if you don't want them in source control, or commit them and let CI pick the right one based on the build context.