Webhook returns HTTP 401
HTTP 401 means the receiver did not accept the request credentials. For webhooks, this most often points to a missing signature header, wrong secret, malformed authorization token, or verification against altered bytes.
Distinguish authentication methods
| Method | Evidence |
|---|---|
| HMAC signature | Provider-specific signature header plus raw body. |
| Bearer token | Authorization header with the expected token and scheme. |
| Basic authentication | Authorization header and matching server configuration. |
| Custom shared secret | Documented header or query value; avoid secrets in URLs where possible. |
Likely causes
- The provider and receiver use secrets from different environments.
- A secret was rotated on one side only.
- A reverse proxy removes or renames the required header.
- The receiver verifies a parsed body rather than the original bytes.
- The signature encoding or prefix does not match the provider contract.
Diagnosis procedure
- Identify the authentication scheme configured for this provider and endpoint.
- Confirm the required header reached the application without logging the full secret or token.
- Compare secret identifiers, environment, rotation time, algorithm, and encoding on both sides.
- For HMAC, recompute the digest over the captured raw body and compare it using a timing-safe function.
- Review proxy and framework middleware for header or body transformations.
- Send a new event after synchronizing credentials.
Return safe errors
Return a short 401 response to the sender, but keep the detailed reason in protected application logs. Do not return the expected signature, secret, or token value.
Verify the fix
- A newly delivered request includes the expected authentication header.
- Verification succeeds without exposing credentials in logs.
- Old credentials no longer work after a completed rotation.