Aliases

An alias is the permanent webhook URL you register in your providers. It's the part that never changes.

An alias is a public webhook URL owned by your account. It looks like <subdomain>.fixedhook.com and is the address you register in Stripe, GitHub, Shopify, or any other provider. Once created, the alias URL is permanent — it does not change when tunnels come and go.

Anatomy of an alias

• Subdomain — the part you pick. It must be 3–32 characters, alphanumeric with hyphens, and not on the reserved list.
• Domain — fixedhook.com (or your own custom domain, when configured).
• Path — anything after the domain. Providers typically require a specific path; you can use whatever you like.

The alias forwards every request to the delivery target you choose: an active local CLI tunnel or a deployed webhook URL. When local tunnel delivery is selected and no tunnel is attached, the relay buffers incoming events so nothing is lost — once you reconnect, the queue flushes.

Delivery settings

Delivery settings let you keep providers pointed at one stable URL, then switch where FixedHook sends the traffic.

For example, your provider can keep sending webhooks to:

https://my-app-dev.fixedhook.com

In the dashboard, open the alias and choose Delivery settings:

• Select Local tunnel to wait for an active CLI tunnel before delivery.
• Select Deployed URL and enter a public HTTPS endpoint, such as https://api.example.com/webhooks/stripe, to forward directly to a deployed service.

Incoming query parameters are appended when FixedHook forwards the request, so provider URLs with query strings continue to work.

Naming rules

A subdomain:

• Is 3 to 32 characters long.
• Starts and ends with an alphanumeric character.
• Can contain lowercase letters, digits, and hyphens.
• Is case-insensitive — MyApp-Dev and myapp-dev resolve to the same alias.
• Cannot match a reserved name (e.g. www, api, admin, dashboard, app).

Alias limits by plan

The free plan is enough to wire up your local dev and one or two test integrations. The Builder plan is the common pick for indie products and active side projects.

Lifecycle

create   →   active   →   (tunnel connects)   →   online
                                  ↓
                            tunnel drops
                                  ↓
                              offline
                                  ↓
                  (events still buffered)
                                  ↓
              (tunnel reconnects)   →   online
                                  ↓
                       delete alias

• Active — the alias exists and is owned by you. The relay accepts traffic.
• Online — a tunnel session is currently attached. Requests are forwarded in real time.
• Offline — no tunnel is attached. The relay accepts traffic and buffers events for replay when a tunnel reconnects.
• Deleted — the alias is removed. Requests return 404. Existing events are retained according to your plan's history window.

The alias vs. the tunnel

This is the part that confuses people. The alias is the destination your provider knows about. The tunnel is how traffic gets from the alias to your code.

You can have many tunnels attach to one alias over the lifetime of your account, but only one can be online at a time. When you start a new tunnel, the previous one is disconnected and the new one takes over.

Stripe  ─────────►  my-app-dev.fixedhook.com  ◄──────────  Tunnel
(always the same)                                  (CLI session, ephemeral)
                                                          ↓
                                                    localhost:3000

The same alias can route to your laptop today, a colleague's laptop tomorrow, a preview deployment next week, and production next month — without your providers ever noticing. Use Delivery settings in the dashboard to switch between the local tunnel and a deployed HTTPS endpoint.

Trial aliases

If you want to try FixedHook without an account, POST /api/v1/auth/trial returns a 12-hour alias and a session token you can hand to the CLI. The alias works the same as a normal alias; it just stops accepting traffic after the TTL expires.

See Trial aliases for the request and response shape.

What an alias does NOT do

• It does not transform payloads. What your provider sends is what your code receives.
• It does not retry automatically. Replay is a manual action in the dashboard, not an automatic retry policy. (Planned for a later release.)
• It does not store the entire request body indefinitely. Bodies are stored in object storage and pruned by the history window of your plan.