Webhook Signature Failures During API Onboarding

A 401 on the first webhook delivery looks like a mistake in their HMAC. Often it is your side: you signed the parsed JSON instead of the raw body, the timestamp tolerance is 30 seconds and their worker is behind, or the secret in the dashboard is for the other environment.

They will not open an issue titled 'I probably did HMAC wrong.' They will try another provider's example, or leave the feature dark. The failure has to introduce itself.

Use distinct codes for missing signature header, stale timestamp, unknown secret version, and digest mismatch. One 'invalid signature' string forces them to binary-search your docs. Four codes let them jump to the right paragraph.

The message should say which header you read and which tolerance you applied. It should not echo the secret or the signature bytes. Those are credentials.

When your API rejects a verification, that rejection is a probe: route, code, SDK or API version, and whether the timestamp fell outside the window. You do not need the payload. You need to know that staging secrets are being used against production URLs.

Ask what they were trying to do only in the CLI or sample receiver, not inside the HTTP 401 body as a questionnaire. The HTTP body stays a stable error object.

If drafts pile up under 'stale timestamp,' lead the quickstart with NTP and the tolerance number. If they pile up under 'digest mismatch,' show the raw-body snippet in the language they installed.

Support deflection here is a better error, not a longer help center article nobody opens from curl.