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 aCompletableFuture, 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));