Provide a way for deserializing EventBridge events

[AlessandroBagnoli]

Hi there!

As noted in the Stripe EventBridge documentation, events delivered via EventBridge have a different schema than standard webhooks due to an additional wrapping layer.

Currently, it seems the SDK's deserialization logic is tightly coupled with signature verification. Since EventBridge events don't use signatures in the same way, there isn't a straightforward way to use the SDK to parse these events into strongly-typed objects.

Proposed Solution:
It would be great if the SDK exposed a method to deserialize these specific EventBridge payloads directly.

Question:
Is there currently a supported way to do this that I might have missed, or should this be considered a new feature request?

Many thanks!

[xavdid]

Hey @AlessandroBagnoli! Thanks for the suggestion.

The current recommendation is to use EventNotification.fromJson(webhookBody, client) instead of client.parseEventNotification(webhookBody, sigHeader, WEBHOOK_SECRET). The latter calls the former under the hood, but assumes validation is already complete (or unnecessary). The rest of the calling code (casting from an EventNotification to a more specific type) is the same.

This isn't documented well, so we'll work on surfacing that!

[AlessandroBagnoli]

Thanks @xavdid ! It would be lovely to have a way to do this without having to pass an instance of a client (similarly to how the Webhook class allows this with static methods)

[xavdid]

That's currently not planned because EventNotifications need to be able to fetch their corresponding events and related objects without relying on global state. So they take a client, allowing users to customize retrieval behavior separate from the rest of an integration.

That said, we're always open to ideas. Can you talk more about your use case?