Implement `WebhookEvent` model

[codebestia]

Represents a parsed, verified webhook event delivered by the Shade platform. The data field should be typed as the corresponding resource model rather than a raw dict.

Proposed Steps:

• Create src/shade/models/webhook.py.
• Fields: id, type: str, data: Any, created_at: datetime, livemode: bool.
• Add a WebhookEventType constants class.
• The Webhook.construct_event() method populates data with the typed model.

Acceptance Criteria:

• WebhookEvent.from_dict(raw_payload) populates all fields.
• event.livemode correctly reflects the event origin.
• event.data is the raw dict at model level; typed model coercion happens in the resource layer.

[lifewithbigdamz]

i would like to work on this issue as a full stack and smart contract developer

[Scepter00]

Hi! I'd like to work on this issue.

I have experience designing typed data models and building SDKs that prioritize clean APIs and maintainability. This issue is a great opportunity to improve the webhook experience by providing a well structured event model while keeping the parsing flow flexible.

My approach will be to implement a WebhookEvent model that accurately represents verified webhook payloads, including the required fields and a dedicated WebhookEventType constants class. I'll ensure WebhookEvent.from_dict() correctly parses and populates all event fields while keeping the model layer responsible only for representing the webhook payload.

I'll preserve the separation of responsibilities by leaving event.data as the raw dictionary within the model and ensuring typed resource coercion happens in the resource layer through Webhook.construct_event(). This keeps the implementation clean, extensible, and aligned with the architecture described in the issue.

I'll also add comprehensive tests covering payload parsing, livemode handling, event type parsing, and the expected model behavior to ensure all acceptance criteria are met.

I'd be happy to take ownership of this issue and contribute a clean, well tested implementation.

[Depo-dev]

Hi team

I’d like to take this one.

My understanding is that WebhookEvent should act as a clean, reliable wrapper around incoming webhook payloads — handling parsing and normalization, but not taking on responsibility for resource-level typing. That separation keeps the model simple and avoids coupling it to specific resource schemas.

I’ll add src/shade/models/webhook.py with a WebhookEvent model that includes id, type, data, created_at, and livemode, along with a small WebhookEventType constants class for known event types. The from_dict method will take the raw payload and map fields safely, including parsing created_at into a proper datetime and correctly setting livemode.

Even though the initial note mentions typed data, I’ll follow the acceptance criteria and keep event.data as the raw dict at this level. Any coercion into typed resource models will happen later in the resource layer, based on event.type.

I’ll also make sure this integrates cleanly with Webhook.construct_event() so it consistently returns a properly constructed WebhookEvent.

Happy to get started.

[grantfox-oss]

🦊 GrantFox — @Depo-dev has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #42)
2. Your PR will be reviewed by the ShadeProtocol maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@Depo-dev's PR #52 was approved and merged by @codebestia.

🏆 @Depo-dev: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (331 total points). Track your full progress on GrantFox.

👏 Great work, @Depo-dev! Keep contributing to ShadeProtocol.