Receive Email Webhooks in Spring Boot

Quick Start: Spring Boot Email Webhook

JsonHook delivers every inbound email as a JSON POST request to your webhook endpoint. Setting up a Spring Boot handler takes less than 5 minutes. Start by initializing your project:

# Add to pom.xml:
# org.springframework.boot
# spring-boot-starter-web

Then create your webhook endpoint. The following example shows the minimal code needed to receive and acknowledge a JsonHook delivery:

@RestController
public class WebhookController {

    @PostMapping("/webhook")
    public ResponseEntity webhook(@RequestBody String body) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        JsonNode payload = mapper.readTree(body);
        String from    = payload.path("email").path("from").asText();
        String subject = payload.path("email").path("subject").asText();
        System.out.println("Email from: " + from + " | Subject: " + subject);
        return ResponseEntity.ok("ok");
    }
}

Point your JsonHook address webhook URL to this endpoint and you will start receiving parsed emails as JSON within seconds of the email arriving.

Full Spring Boot Implementation

The quick start example above is enough to get started, but a production implementation should include signature verification, structured error handling, and proper HTTP response codes. The complete example below demonstrates all of these patterns together.

This implementation verifies the X-JsonHook-Signature header to confirm the request genuinely came from JsonHook, parses the full email payload, and returns the appropriate HTTP status codes to trigger or suppress retries.

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.concurrent.CompletableFuture;

@RestController
public class WebhookController {

    private static final String SECRET = System.getenv("JSONHOOK_WEBHOOK_SECRET");
    private final ObjectMapper mapper = new ObjectMapper();

    private boolean verifySignature(byte[] body, String sigHeader) throws Exception {
        if (sigHeader == null || sigHeader.isEmpty()) return false;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(SECRET.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        String computed = HexFormat.of().formatHex(mac.doFinal(body));
        return MessageDigest.isEqual(
            computed.getBytes(StandardCharsets.UTF_8),
            sigHeader.getBytes(StandardCharsets.UTF_8)
        );
    }

    @PostMapping("/webhook")
    public ResponseEntity webhook(HttpServletRequest request) throws Exception {
        byte[] body = request.getInputStream().readAllBytes();
        String sig  = request.getHeader("X-JsonHook-Signature");

        if (!verifySignature(body, sig)) {
            return ResponseEntity.status(401).body("Unauthorized");
        }

        JsonNode payload = mapper.readTree(body);
        String timestamp = payload.path("timestamp").asText();
        String address   = payload.path("address").asText();
        JsonNode email   = payload.path("email");

        // Respond immediately, then process
        CompletableFuture.runAsync(() -> {
            System.out.printf("[%s] %s: %s from %s%n",
                timestamp, address, email.path("subject").asText(), email.path("from").asText());
        });

        return ResponseEntity.ok("ok");
    }
}

The webhook handler returns 200 immediately after queuing the email for processing. Avoid doing expensive work (database writes, API calls) synchronously inside the handler — process the payload in a background job to stay within JsonHook's 10-second response timeout.

Parsing the Webhook Payload

Every JsonHook delivery is an HTTP POST with Content-Type: application/json. The payload follows a consistent schema regardless of the originating email client or provider:

ObjectMapper mapper = new ObjectMapper();
JsonNode payload = mapper.readTree(body); // body is byte[]

String event     = payload.path("event").asText();
String timestamp = payload.path("timestamp").asText();
String address   = payload.path("address").asText();

JsonNode email   = payload.path("email");
String from      = email.path("from").asText();
String subject   = email.path("subject").asText();
String textBody  = email.path("textBody").asText();
String htmlBody  = email.path("htmlBody").asText();

for (JsonNode att : email.path("attachments")) {
    String filename    = att.path("filename").asText();
    String contentType = att.path("contentType").asText();
    int    size        = att.path("size").asInt();
    System.out.printf("  %s (%s, %d bytes)%n", filename, contentType, size);
}

Key fields in the payload:

• event — Always "email.received" for inbound email events
• timestamp — ISO 8601 timestamp of when JsonHook received the email
• address — The JsonHook inbound address that received the email (e.g., [email protected])
• email.from — Sender address string, e.g., "Alice <[email protected]>"
• email.to — Array of recipient address strings
• email.subject — Email subject line
• email.textBody — Plain text body of the email (may be empty if HTML-only)
• email.htmlBody — HTML body of the email (may be empty if plain-text-only)
• email.attachments — Array of attachment objects, each with filename, contentType, size, and contentId

Verifying Webhook Signatures

JsonHook signs every webhook delivery using HMAC-SHA256. The signature is included in the X-JsonHook-Signature request header as a hex digest. To verify it, compute the HMAC-SHA256 of the raw request body using your address's webhook secret and compare it to the header value.

Your webhook secret is returned when you create an inbound address via the API (POST /api/addresses). Store it as an environment variable — never hard-code it.

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;

private boolean verifyJsonHookSignature(byte[] body, String sigHeader, String secret)
        throws Exception {
    if (sigHeader == null || secret == null) return false;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    String computed = HexFormat.of().formatHex(mac.doFinal(body));
    // MessageDigest.isEqual is constant-time
    return MessageDigest.isEqual(
        computed.getBytes(StandardCharsets.UTF_8),
        sigHeader.getBytes(StandardCharsets.UTF_8)
    );
}

Always verify the signature before processing the payload. Return 401 for invalid signatures so that legitimate retries from JsonHook (which always include a valid signature) are distinguishable from spoofed requests.

Error Handling Best Practices

Reliable webhook handling requires careful attention to error responses. JsonHook uses your HTTP response code to decide whether to retry a delivery:

• Return 200 quickly: Acknowledge receipt immediately and process asynchronously. JsonHook will retry any non-2xx response.
• Return 400 for bad requests: If the payload fails your own validation (not signature — use 401 for that), return 400 to prevent retries of malformed deliveries.
• Return 500 to trigger retries: If your downstream system is temporarily unavailable, returning 500 causes JsonHook to retry with exponential backoff (up to 5 attempts over ~1 hour).
• Never return 200 before verifying the signature: Doing so silently accepts spoofed requests.

Spring Boot-specific tips:

• Read the request body with request.getInputStream().readAllBytes() rather than relying on Spring's @RequestBody annotation, which may deserialize the body before you can compute the HMAC
• Use MessageDigest.isEqual() for constant-time comparison of the computed and provided HMAC hex strings
• Use CompletableFuture.runAsync() or Spring's @Async on a service method to process the email payload without blocking the controller thread
• Add spring.mvc.throw-exception-if-no-handler-found=true and a @ControllerAdvice exception handler to return structured error responses instead of Spring's default HTML error pages

Spring Boot Framework Tips

Spring Boot provides several conveniences that make webhook handling cleaner. Here are framework-specific patterns to use when integrating JsonHook:

• Register your webhook route before any authentication middleware — the JsonHook request does not carry user credentials, only the HMAC signature.
• Use raw body access for signature verification. Many Spring Boot frameworks parse the body automatically — make sure you are hashing the raw bytes, not the re-serialized parsed object.
• Use a dedicated route or controller file for webhook handlers to keep the codebase organized as you add more inbound address integrations.
• Log the address field from every payload to track which inbound address received the email — useful for multi-address setups.
• Consider using Spring Boot's built-in request validation or a schema library (e.g., Zod, Pydantic, etc.) to validate the payload structure after signature verification.