Skip to content

Add error messages to help users debug signature verification failures - #1995

Merged
mark-kogan-stripe merged 5 commits into
masterfrom
orrc/tse-2678-signature-debug-metadata
Nov 9, 2026
Merged

mark-kogan-stripe merged 5 commits into
masterfrom
orrc/tse-2678-signature-debug-metadata

Conversation

@orrc

@orrc orrc commented Oct 13, 2026 •

Copy link
Copy Markdown
Member

Why?

Webhook signature verification failures are often caused by using the wrong signing secret, or modifying the payload before passing it into the verification function. However, we're currently unable to provide developers with any hints as to why verification is failing.

What?

The stripe-signature HTTP header sent with each event will start to include metadata about the event destination and the event payload.

This update uses that metadata, when present, to provide more detailed error messages in the case of signature verification failures. These can help developers narrow down what might be wrong with their code or configuration.

No changes are made to the actual signature verification process; this just updates how error messages are generated.

See Also

https://go/j/TSE-2678
https://go/j/SECREV-5921

Configuration

  • skip-changefile: This PR is not a user-facing change, so there's no changefile.

The stripe-signature header may now include additional metadata about
the event destination and the event being sent. These can help narrow
down the reason why signature verification failed.

No changes are made to the verification process; this just updates how
error messages are generated, if the metadata is present in the header.
@orrc
orrc requested a review from a team as a code owner October 13, 2026 10:15
@orrc
orrc requested review from jar-stripe and removed request for a team October 13, 2026 10:15
@jar-stripe
jar-stripe requested a balanced review from Copilot October 14, 2026 18:47

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unauthenticated metadata can currently produce misleading or injected diagnostic messages.

1 open finding
What changed in this PR

Adds webhook signature-failure diagnostics using metadata from the Stripe-Signature header.

Changes:

  • Diagnoses signing-secret and payload mismatches.
  • Validates and extracts diagnostic metadata.
  • Adds tests and a patch changefile.
File Description
lib/​stripe/​webhook.rb Generates detailed verification errors.
test/​stripe/​webhook_test.rb Tests diagnostic behavior.
test/​test_helper.rb Supports metadata in test headers.
.hark/​changes/​2026-10-12_orrc_webhook-signature-diagnostics.change.md Documents the user-facing change.

🧠 Review effort: Balanced


💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread lib/stripe/webhook.rb Resolved
Comment thread lib/stripe/webhook.rb Resolved
Comment thread lib/stripe/webhook.rb Resolved
Comment thread lib/stripe/webhook.rb Resolved
@mark-kogan-stripe
mark-kogan-stripe enabled auto-merge (squash) November 9, 2026 18:17
@mark-kogan-stripe
mark-kogan-stripe merged commit 7e43772 into master Nov 9, 2026
12 checks passed
@mark-kogan-stripe
mark-kogan-stripe deleted the orrc/tse-2678-signature-debug-metadata branch November 9, 2026 18:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants