[Bug]: There is no useful documentation on how to use webhook events

[ribtoks]

What happened?

When you're trying to use this SDK, it's not clear at all how to handle any, even the most simple webhook.

Say, I want to handle "subscription created" webhook. What data types should I use? paddle.SubscriptionCreatedEvent or maybe paddlenotification.SubscriptionCreated. I don't want to manually map json from the doc page to all types that look like that json, which are at least 3 (Notification and those two I mentioned earlier). It will be very helpful if there were code examples.

Not to mention that now every person who wants to use this code, needs to at least partically copy-paste the switch-case from unmarshalEvent() (file events.go). Would be great if there was a recommended way to do this in an easy form.

Steps to reproduce

1. Just try to integrate with this SDK in any real-world example.
2. ...

What did you expect to happen?

To find code examples that show at leaast any way of using this.

Logs

No response

[ribtoks]

I eventually found something that looks like what I needed in #34 . But my point still stands: it is not documented what types are for what, there's no any reference to that example in any "well-known" documentation place (e.g. *.md file) or in the official docs website. I think there's a lot of room for improvement here.

[mikeymike]

Hi @ribtoks ... We greatly appreciate the feedback around this. We settled on the use of testable examples within the SDK to ensure that the examples we provide show to be functional and compile as expected otherwise a build would fail at PR.

I think as a minimum we need to ensure we're calling these out in the README.md so it's easier to find, we'll get this actioned ASAP.

I'll also discuss with the team ways in which we can improve this across the board to provide a consistent approach with better documentation of our types and their usage.

I'll keep this issue open while we look to make some initial improvements to the README, if you have any other issues, concerns or questions please continue to raise them 🙏

[ribtoks]

Thank you!

One other comment is that it's hard to leave feedback for developers. GitHub Issues templates effectively say "if you want to leave feedback - send it to the [black hole] [email protected]". This current issue is effectively a feedback, it's obviously not a "bug" in a classical sense, but I figured it's the fastest way to get somebody competent to look into this. One way would be to have "Feedback" issue templates available or to have Discussions open.

One "nitpick" comment about code example from #34 is that you are introducing a custom type (Webhook) that has a maintenance cost to it. Now author of the code has to check every time when they update the library for breaking changes - literally many were already made! - if the paddlenotification.EventTypeName is still called like that, if the json fields mapping is correct etc. etc. I can see you have paddlenotification.GenericNotificationEvent, which usage maybe is more "resilient" at the expense of parsing "few more fields from json". But this is a nitpick after all.