Stop Writing Webhook Boilerplate in Spring Boot

#java #springboot #webhook #opensource

If you've ever needed to send outgoing webhooks from a Spring Boot application, you know the drill. You wire up an HTTP client, implement HMAC signing, add retry logic, bolt on a circuit breaker, set up an async thread pool, and somehow fit audit logging in too, before you've even written a single line of business logic.

I got tired of doing this repeatedly across projects, so I built
spring-webhook-sender - a Spring Boot 3.x starter that handles all of it for you.

What it does

Drop in one dependency and inject WebhookClient. That's it. Under the hood it handles:

HMAC-SHA256 signing - every request gets an X-Webhook-Signature: sha256=<hmac> header automatically
Retry with exponential backoff - 5xx and network errors are retried; 4xx are not
HTTP 429 Retry-After support - respects the server's retry window
Per-endpoint circuit breaker - powered by Resilience4j; a broken endpoint only trips its own circuit
Non-blocking async dispatch - sendAsync() returns a CompletableFuture, your thread is never blocked
Audit logging - SLF4J by default, pluggable to a database via a single bean

Installation

<dependency>
    <groupId>io.github.karunarathnad</groupId>
    <artifactId>spring-webhook-sender</artifactId>
    <version>2.0.1</version>
</dependency>

Requires Java 17+ and Spring Boot 3.2+. No extra configuration needed — Spring Boot auto-configuration wires everything up.

Usage

@Service
public class OrderService {

    @Autowired
    private WebhookClient webhookClient;

    private static final WebhookEndpoint PAYMENT_ENDPOINT = WebhookEndpoint.builder()
            .id("payment-service")
            .targetUrl("https://payments.example.com/webhooks")
            .secret(System.getenv("PAYMENT_WEBHOOK_SECRET"))
            .build();

    public void onOrderCreated(Order order) {
        WebhookEvent event = WebhookEvent.builder()
                .eventType("order.created")
                .payload(order)
                .build();

        webhookClient.sendAsync(event, PAYMENT_ENDPOINT)
                .thenAccept(result -> log.info("delivered={} attempts={}", 
                    result.success(), result.totalAttempts()));
    }
}

The JSON payload sent to the endpoint looks like this:

{
  "eventId": "a3f1c2d4-...",
  "eventType": "order.created",
  "occurredAt": "2026-05-10T08:30:00Z",
  "payload": { "orderId": "ORD-001", "amount": 99.99 }
}

Configuration

All settings have sensible defaults. Override only what you need in application.yml:

webhook:
  retry:
    max-attempts: 3
    initial-interval: 1s
    multiplier: 2.0
    max-interval: 30s
  circuit-breaker:
    failure-rate-threshold: 50
    minimum-number-of-calls: 10
  async:
    core-pool-size: 4
    max-pool-size: 16

Extending

Need to persist delivery records to a database? Register one bean:

@Bean
public AuditLogger webhookAuditLogger(WebhookAuditRepository repo) {
    return record -> repo.save(toEntity(record));
}

Need a custom signing strategy? Override SignatureStrategy. Need snake_case JSON? Override webhookObjectMapper. The library gets out of your way when you need it to.

Verifying on the receiving side

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(UTF_8), "HmacSHA256"));
String expected = "sha256=" + HexFormat.of().formatHex(mac.doFinal(rawBody.getBytes(UTF_8)));
String received = request.getHeader("X-Webhook-Signature");

// constant-time comparison to prevent timing attacks
boolean valid = MessageDigest.isEqual(expected.getBytes(UTF_8), received.getBytes(UTF_8));

DEV Community