MT-22022: Add webhook signature verification helper

[Rabsztok]

Motivation

Expose a helper so Java users don't have to re-implement Mailtrap's HMAC-SHA256 webhook signature check on every receiver.

• Algorithm: https://docs.mailtrap.io/email-api-smtp/advanced/webhooks#verifying-the-signature
• Jira: MT-22022

Changes

• io.mailtrap.webhooks.WebhookSignatures.verify(String payload, String signature, String signingSecret): boolean. HMAC-SHA256 over the raw body, constant-time compare via MessageDigest.isEqual. Returns false (never throws) on null / empty / wrong-length / non-hex inputs.
• src/test/java/io/mailtrap/webhooks/WebhookSignaturesTest.java pins the cross-SDK fixture (payload + signing_secret + expected digest) shared verbatim across all six official Mailtrap SDKs to guarantee byte-for-byte parity.
• examples/.../webhooks/WebhookSignatureExample.java — runnable usage snippet (main method that asserts valid + bad inputs).
• README — new "Verifying webhook signatures" subsection.

How to test

CI runs the full maven test suite. Manually:

mvn -q compile
javac -cp target/classes -d /tmp/mt examples/java/io/mailtrap/examples/webhooks/WebhookSignatureExample.java
java -cp target/classes:/tmp/mt io.mailtrap.examples.webhooks.WebhookSignatureExample

The last command should exit 0 with no output.

Companion PRs

Coordinated rollout across all six official SDKs (same algorithm, same shared fixture):

• mailtrap-ruby#110
• mailtrap-python#67
• mailtrap-php#66
• mailtrap-nodejs#130
• mailtrap-java#53 (this PR)
• mailtrap-dotnet#242

Summary by CodeRabbit

• New Features

  • Added webhook signature verification for Mailtrap webhooks using industry-standard HMAC-SHA256 encryption.

• Documentation

  • Added "Verifying webhook signatures" section to README with implementation guidance and practical code example demonstrating signature validation.

• Tests

  • Added comprehensive test coverage for webhook signature verification functionality.

[coderabbitai]

Warning

Review limit reached

@Rabsztok, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 59 minutes and 47 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f18a6c51-e6c7-4a0e-b655-21eda15ba952

📥 Commits

Reviewing files that changed from the base of the PR and between bfe3bad and 75cd558.

📒 Files selected for processing (2)

• README.md
• examples/java/io/mailtrap/examples/webhooks/WebhookSignatureExample.java

📝 Walkthrough

Walkthrough

This PR adds webhook signature verification to the Mailtrap Java SDK. A new WebhookSignatures utility provides verify(payload, signature, signingSecret) to validate HMAC-SHA256 signatures. The implementation includes comprehensive tests covering valid inputs, invalid secrets, tampered payloads, format errors, and null/empty edge cases. Documentation and example code show how to use the API.

Changes

Webhook Signature Verification

Layer / File(s)	Summary
Core signature verification implementation src/main/java/io/mailtrap/webhooks/WebhookSignatures.java	WebhookSignatures utility class exposes SIGNATURE_HEX_LENGTH (64) and a static verify(payload, signature, signingSecret) method that validates HMAC-SHA256 signatures, performing constant-time comparison via MessageDigest.isEqual. The method returns false for missing/empty inputs, incorrect length, non-hex signatures, and crypto errors (throws IllegalStateException only for unusable crypto algorithm/provider).
Test suite validation src/test/java/io/mailtrap/webhooks/WebhookSignaturesTest.java	WebhookSignaturesTest validates verify behavior against shared cross-SDK HMAC fixtures, checking happy path (valid input), wrong signing secret, tampered payload, signature length mismatches (short/long), non-hex characters, empty signature/secret/payload, and null inputs. Includes a round-trip test that recomputes HMAC-SHA256 via JDK Mac and asserts the result matches the embedded fixture.
Example code and README documentation examples/java/io/mailtrap/examples/webhooks/WebhookSignatureExample.java, README.md	WebhookSignatureExample demonstrates HMAC-SHA256 signature creation using JDK Mac, verification via verify(), and shows that invalid signatures return false without throwing. README "Verifying webhook signatures" section documents the Mailtrap-Signature header, raw payload requirement, and provides a usage example with the API.

🎯 3 (Moderate) | ⏱️ ~20 minutes

🐰 Webhooks now sign with trusted HMAC,
Constants and tests keep signatures intact,
Java devs can verify each fact! 🔐

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 61.11% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and clearly summarizes the main change: adding a webhook signature verification helper to the Mailtrap Java SDK.
Description check	✅ Passed	The description covers all required template sections with substantial detail: clear motivation, comprehensive changes list, test instructions, and coordination notes across SDKs.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch MT-22022-webhook-signature-verification

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Rabsztok]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Rabsztok]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Rabsztok]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.