The canary

A canary link is a short fwd2 link with one extra job. When someone follows it, fwd2 POSTs a small signed JSON message to a webhook URL you chose at creation time. The visitor sees a normal redirect to whatever URL you set. Nothing in the response, the timing, or the headers reveals that the link was a canary.

Why you would use one

The intended use is to plant a uniquely-shaped URL inside something you do not expect to be opened. A private document. A credential file. A backup archive. A vendor dataset. When that URL is followed, you learn the thing got opened. You do not learn who opened it. That is the point of a canary, and that is also the limit of a canary.

What makes a fwd2 canary different

Three properties, all on purpose.

It looks like a normal short link, because it is one. Same path shape, same redirect, same response headers. There is no canary=true tell on the wire. Anyone inspecting the link or its redirect target sees a plain shortener.

It records that it fired. It does not record who. No client IP, no User-Agent, no Referer, no cookie, no request id. The fields fwd2 keeps are the canary code, the count, and the timestamps. The fields fwd2 will tell you about are the canary code, the count, and the timestamps. There is nothing else to leak because there is nothing else stored.

The alert is verifiable. The webhook body is signed with HMAC-SHA256 and a key only fwd2 and your server know. The signature, a key id, and the body timestamp ride in three response headers. A receiver that verifies the signature and enforces a five-minute window on the timestamp can prove the alert came from fwd2 and is not a replay. See the api for the wire format. The body fields are event, code, fired_at, timestamp, and nonce; no target URL, key, IP, User-Agent, Referer, cookie, or per-visitor id is sent.

The honest limits

A canary tells you volume and timing. It tells you a canary fired, it tells you how many times, it tells you the first and the last fire. It does not tell you who. It does not tell you where from. It does not give you a dashboard of visitors because fwd2 does not watch visitors. If you need attribution, the canary URL itself has to carry the attribution. Plant a different canary in each place; the code that fires is the answer.

How to set one up

If you want to do it from this site, use create a canary link. If you want to do it from your own client, use the API.

Send a POST /shorten with canary: true and a webhook_url. The webhook URL must be https:// and must resolve to a public address. fwd2 stores the webhook URL write-only and never echoes it in any response. The shorten response is the same shape as for a plain link, with one extra canary: true flag so you can confirm the opt-in took. The exact request and response shapes, the validation rules, and the failure modes are documented on the api.

The single key

A canary has one revocation key, like every fwd2 link. The same key revokes the link, and the same key reads the fire status if your webhook ever missed a delivery. There is no second secret to manage. See the key for how that one key is generated, stored, and used.

If you want it to vanish after the first hit

Pass self_destruct_on_fire: true at creation. The very first fire delivers the webhook, then deletes the link before the visitor finishes redirecting. The second visitor sees a normal 404. A self-destructed canary and a revoked canary look identical from the outside. Tell fwd2 it leaked, then make it dead.