feat: return parsed payload from Webhooks.verify

[mayankbohradev]

What

Webhooks.verify now returns the parsed webhook event after a successful HMAC check, matching the documented contract and the Node SDK.

Also adds TypedDicts for webhook event payloads (WebhookEventPayload and per-event types), including message_id on email event data per the current webhook docs.

Why

Docs say verify should throw on invalid webhooks and otherwise return the parsed payload:

https://resend.com/docs/webhooks/verify-webhooks-requests

The Node SDK already does this (verify(...): WebhookEventPayload). Python returned None, so callers had to json.loads the raw body again (see the previous examples/webhook_receiver.py flow).

Outbound email webhook docs also include data.message_id (for example https://resend.com/docs/webhooks/emails/sent). Retrieve/list already expose message_id on Email (#232); webhook payload types did not.

Behavior notes

• Existing callers that ignore the return value keep working.
• Invalid signature / missing fields / expired timestamp still raise ValueError.
• Valid signature with non-JSON body now raises ValueError (failed to parse webhook payload), instead of returning None.
• CamelCase fields such as bounce.subType and click.ipAddress match the API payload shape.

Testing

Local gate (same checks CI runs):

• tox -e lint — pass
• tox -e mypy — pass (167 source files)
• tox -e py -- tests/webhooks_test.py — 16 passed
• tox -e py — 491 passed

New / updated coverage:

• verify returns parsed email.sent payload including message_id
• verify returns email.received payload including message_id / received_for
• verify raises on valid signature + invalid JSON
• example updated to use the returned payload

---

Summary by cubic

Make Webhooks.verify return the parsed webhook event after signature checks, matching the docs and the Node SDK. Adds TypedDicts for all webhook payloads, including data.message_id on email events.

• New Features

  • Webhooks.verify returns WebhookEventPayload on success; raises ValueError when the body is not valid JSON.
  • Added WebhookEventPayload and per-event TypedDicts; exported in resend.
  • Updated examples/webhook_receiver.py and tests to use the returned payload. TypedDicts mirror API field names (camelCase).

• Migration

  • Use the returned event instead of calling json.loads on the body.
  • Handle ValueError for valid signatures with non-JSON bodies.
  • No changes needed if you ignore the return value.

^{Written for commit 30e078b. Summary will update on new commits.}