Document that the entrypoint UUID is the authentication and shared secrets are never used #301

New Issue

2026-08-25T22:34:36+02:00

clawbot commented

2026-08-25 22:34:36 +02:00

Settled ruling from sneak, 2026-08-25:

> we are never using shared secrets with Webhooks. Webhooker creates UUIDs for the Webhooks. The UUID is the secret. Get that into your head.

This is already the implemented reality — inbound signature verification was removed in #279, closing #67 and #241. What is missing is the rule stated as a rule, so that a future contributor proposing HMAC is contradicted by the docs rather than merely unimplemented.

Definition of done — README.md states, prominently:

The entrypoint UUID in the receiver URL /webhook/{uuid} is the credential. Nothing else authenticates an inbound webhook: no shared secret, no HMAC signature, no token header, no second factor.
Never add any of those to the receiver. It was considered and rejected.
Operator consequences: the URL is a capability, so treat it as a secret — keep it out of logs, ticket bodies and screenshots; rotating means minting a new entrypoint, not changing a key.
A sender that cannot be given a secret URL and only supports signed payloads is a constraint on that integration, to be raised — not grounds to reintroduce shared secrets.

Also: audit README.md and the code comments for stale signature/secret language left behind by the removal, and correct anything that contradicts the rule, in the same PR.

Docs-only; no behaviour change.

Settled ruling from sneak, 2026-08-25: > we are never using shared secrets with Webhooks. Webhooker creates UUIDs for the Webhooks. The UUID is the secret. Get that into your head. This is already the implemented reality — inbound signature verification was removed in https://git.eeqj.de/sneak/webhooker/pulls/279, closing https://git.eeqj.de/sneak/webhooker/issues/67 and https://git.eeqj.de/sneak/webhooker/issues/241. What is missing is the rule stated as a rule, so that a future contributor proposing HMAC is contradicted by the docs rather than merely unimplemented. Definition of done — `README.md` states, prominently: - The entrypoint UUID in the receiver URL `/webhook/{uuid}` is the credential. Nothing else authenticates an inbound webhook: no shared secret, no HMAC signature, no token header, no second factor. - Never add any of those to the receiver. It was considered and rejected. - Operator consequences: the URL is a capability, so treat it as a secret — keep it out of logs, ticket bodies and screenshots; rotating means minting a new entrypoint, not changing a key. - A sender that cannot be given a secret URL and only supports signed payloads is a constraint on that integration, to be raised — not grounds to reintroduce shared secrets. Also: audit `README.md` and the code comments for stale signature/secret language left behind by the removal, and correct anything that contradicts the rule, in the same PR. Docs-only; no behaviour change.

clawbot referenced this issue from a commit

2026-08-25 22:38:56 +02:00

State the UUID-is-the-credential rule as a rule (closes #301)

clawbot referenced a pull request that will close this issue

2026-08-25 22:39:11 +02:00

State the UUID-is-the-credential rule as a rule (closes #301) #302

clawbot commented

2026-08-25 22:39:33 +02:00

#302.

The rule now lives in ## The entrypoint URL is the authentication secret, stated as a decision rather than a description, with the operator consequences and the signed-payload-sender case; it is pointed to from the intro, the Authentication list (which said nothing about the receiver before) and the Security list.

One piece of stale language found and fixed: a comment in internal/delivery/redirect_test.go referred to "the inbound signature the receiver verifies", which in this repo's vocabulary names /webhook/{uuid}. The verifier is the delivery target's endpoint.

Disclosure: REPO_POLICIES.md deliberately untouched — it is the cross-project synced policy doc, so a webhooker-specific rule does not belong in it. Its "when in doubt, harden" clause is the sentence a future HMAC proposal will cite; only the README answers it.

https://git.eeqj.de/sneak/webhooker/pulls/302. The rule now lives in `## The entrypoint URL is the authentication secret`, stated as a decision rather than a description, with the operator consequences and the signed-payload-sender case; it is pointed to from the intro, the Authentication list (which said nothing about the receiver before) and the Security list. One piece of stale language found and fixed: a comment in `internal/delivery/redirect_test.go` referred to "the inbound signature the receiver verifies", which in this repo's vocabulary names `/webhook/{uuid}`. The verifier is the delivery target's endpoint. Disclosure: `REPO_POLICIES.md` deliberately untouched — it is the cross-project synced policy doc, so a webhooker-specific rule does not belong in it. Its "when in doubt, harden" clause is the sentence a future HMAC proposal will cite; only the README answers it.

sneak closed this issue

2026-08-30 04:05:38 +02:00

sneak referenced this issue from a commit

2026-08-30 04:05:40 +02:00

State the UUID-is-the-credential rule as a rule (closes #301) (#302)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/webhooker#301