Package io.mailtrap.webhooks

Class WebhookSignatures

java.lang.Object

io.mailtrap.webhooks.WebhookSignatures

public final class WebhookSignatures
extends Object

Helpers for verifying inbound Mailtrap webhook signatures.

Mailtrap signs every outbound webhook by computing HMAC-SHA256(signing_secret, raw_request_body) and sending the lowercase hex digest in the Mailtrap-Signature HTTP header. To authenticate a webhook on the receiver side, compute the same digest using the signing_secret returned when the webhook was created and compare it to the value of the header in constant time.

The comparison is performed with MessageDigest.isEqual(byte[], byte[]) to avoid timing side-channels.

The method never throws on inputs that could plausibly arrive over the wire (empty strings, wrong-length signatures, non-hex characters, missing secret) — it simply returns false. This makes it safe to call directly from a request handler without wrapping in try/catch.

See Also:

• Mailtrap docs — Verifying the signature

Field Summary

Fields

Modifier and Type	Field	Description
static final int	SIGNATURE_HEX_LENGTH	Hex-encoded HMAC-SHA256 signature length (SHA-256 produces 32 bytes / 64 hex chars).

Method Summary

Modifier and Type	Method	Description
static boolean	verify(String payload, String signature, String signingSecret)	Verifies the HMAC-SHA256 signature of a Mailtrap webhook payload.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

SIGNATURE_HEX_LENGTH

public static final int SIGNATURE_HEX_LENGTH

Hex-encoded HMAC-SHA256 signature length (SHA-256 produces 32 bytes / 64 hex chars).

See Also:

• Constant Field Values

Method Details

verify

public static boolean verify(String payload,
 String signature,
 String signingSecret)

Verifies the HMAC-SHA256 signature of a Mailtrap webhook payload.

Parameters:

payload - the raw request body, exactly as received. Do not parse and re-serialize the JSON — re-encoding may reorder keys or alter whitespace and invalidate the signature. With Spring use @RequestBody byte[] or read the body directly from HttpServletRequest.getInputStream() on the webhook route so the body is preserved verbatim.

signature - the value of the Mailtrap-Signature HTTP header (lowercase hex string).

signingSecret - the webhook's signing_secret, returned by the Webhooks API on webhook creation.

Returns:

true if the signature is valid for the given payload and secret, false otherwise (including any null/empty input, wrong-length or non-hex signatures).