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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b95571ec-02e0-4f1e-95e8-ff2a2324484b

📥 Commits

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

📒 Files selected for processing (4)

• README.md
• examples/java/io/mailtrap/examples/webhooks/WebhookSignatureExample.java
• src/main/java/io/mailtrap/webhooks/WebhookSignatures.java
• src/test/java/io/mailtrap/webhooks/WebhookSignaturesTest.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 docstrings

• Create stacked PR
• Commit on current branch

🧪 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.