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?

[xavdid]

@AlessandroBagnoli It was pointed out to me internally that you were probably using Snapshot events (the events that we've had for a long time) not EventNotifications (new "thin" events). If that's the case, fromJson won't help you since it's the wrong type-- sorry about that!

In that case, we do need better tools to work with Event bridge and that work is already planned 😁

[AlessandroBagnoli]

@AlessandroBagnoli It was pointed out to me internally that you were probably using Snapshot events (the events that we've had for a long time) not EventNotifications (new "thin" events). If that's the case, fromJson won't help you since it's the wrong type-- sorry about that!

In that case, we do need better tools to work with Event bridge and that work is already planned 😁

@xavdid Yep, exactly. We are using snapshots. Any timeline you can share? 👀

[xavdid]

No timeline unfortunately, but i'll let you know more when we have it!

[xavdid]

@AlessandroBagnoli I'm taking a look at this now and was hoping you could provide a little context / sample code for how you're hoping to use the incoming event.

1. Is your code running on an AWS surface, like a lambda?
2. And you're using the stripe java SDK in there to interact with the incoming event?
3. Is the event (and it's envelope) available as a string? or does it arrive into your function as some sort of Java class? If the latter, can you turn it back into a string to the SDK can re-parse it?
4. How are you working around this limitation now? Any code you can provide is super helpful!