add/adjust event parsing helpers

[xavdid]

Why?

Historically, our webhook parsing logic has been closely tied to signature validation (because the expectation is that users verify webhooks' authenticity before use). But, as the webhook handling experience has grown in complexity over time, our helper methods haven't kept up.

In addition to the classic parse+verify & handle, we also support / encourage :

• using cloud providers (like AWS EventBridge and Azure Event Grid), which don't require validation at all
• validating & ACKing an event quickly, then queuing it up for later processing
• unit tests w/ signed test payloads

This gives us 4 use cases that each need a subset of helper methods:

case	verify	parse	parseAndVerify	signTestPayload
process immediately			✅	✅
verify, queue, process later	✅	✅		✅
process immediately (cloud provider)		✅
queue, process later (cloud provider)		✅

To support these workflows, we need all of these methods publicly available in every SDK:

1. constructEvent(payload, signature, ...) (parse + verify)
2. parseEventNotification(payload, signature, ...) (parse + verify)
3. constructEventWithoutVerification(payload) (parse, supports both direct webhooks and cloud provider envelopes)
4. parseEventNotificationWithoutVerification(payload) (parse, supports both direct webhooks and cloud provider envelopes)
5. verify(payload, signature, secret, ...)
6. signTestPayload(payload, secret)

The exact naming & arguments vary by language, but each SDK should provide roughly the same capabilities.

Important

For reviewers: the exact error messages are a little inconsistent between SDKs right now. Everything throws in the right place, but we're still iterating on some of the naming. We're trying out "thin event notification" as a descriptor on some of these surfaces. We're planning to have this all cleaned up by the GA launch of interop events; ignore exact messages for now.

What?

Note

these notes generic across all the SDKs; see Changelog below for the SDK-specific list of changes

• add missing event handling methods to StripeClient & Webhook classes, where relevant.
• Add an internal-facing maybe_extract_from_cloud_provider_envelope for handling wrapped events without the user having to think about it
• centralize some event parsing logic; adjusting accepted types for some methods
• adjust some error messages
• add tests
• update docstrings
• python: update claude instructions

See Also

• stripe/stripe-java#2201
• DEVSDK-3085
• DEVSDK-3210

Changelog

• Added methods that return their respective Event/EventNotification class instances without verifying authenticity. Use them when you've previously verified an event (e.g. you verified, put the event in a queue, and are now processing). Supports events from AWS EventBridge and Azure Event Grid natively.
  • Webhook.construct_event_without_verification(payload)
  • StripeClient.construct_event_without_verification(payload)
  • StripeClient.parse_event_notification_without_verification(payload)
• Added WebhookSignature.generate_signature_header(payload, secret, timestamp=None), which computes a full Stripe-Signature header for the given payload. Useful for unit tests!