Webhook Management Platform - Core¶
Validate, enrich, batch/compress, and publish incoming webhook events with retry, rate-limit, and dead-letter support.
Pass a WebhookEventDTO to WebhookProcessingService after request validation. Configure provider-specific limits and retry/batching settings consciously; the security property defaults constrain payloads and accepted request types.
| Maven artifact | Packaging | Source project |
|---|---|---|
org.fireflyframework:fireflyframework-webhooks-core |
jar |
modules/webhooks/fireflyframework-webhooks-core |
Part of Event-driven integration.
In the onboarding service¶
Validate/enrich the inbound verification-provider request and publish its configured event. Receiving a webhook is distinct from updating the onboarding application; the worker supplies that business operation.
Add the component¶
Installation and version availability explains source builds and published releases.
<dependency>
<groupId>org.fireflyframework</groupId>
<artifactId>fireflyframework-webhooks-core</artifactId>
<version>26.10.20-SNAPSHOT</version>
</dependency>
Quick start¶
The Java examples in this section are API fragments for application code. Use the stated imports and supply the application-owned collaborators described alongside them.
Construct a provider-neutral WebhookEventDTO, validate the actual HTTP request with WebhookValidator, and pass the DTO to the injected processing service:
processingService is org.fireflyframework.webhooks.core.services.WebhookProcessingService; use the exact package link in the API table. event carries provider name, JSON payload, event identifier, and request metadata. The web controller is the reference for the complete validation/metrics/delegation order. Configure the destination transport before expecting processing to publish an event, and choose batching/compression/retry settings from the source-backed namespaces below.
Configuration and wiring¶
The firefly.webhooks.batching namespace is bound by BatchingProperties.java. Nested configuration is declared in the linked class. Defaults are the field initializers.
| Setting | Java type | Source default |
|---|---|---|
firefly.webhooks.batching.enabled |
boolean |
false |
firefly.webhooks.batching.max-batch-size |
int |
100 |
firefly.webhooks.batching.max-wait-time |
Duration |
Duration.ofSeconds(1) |
firefly.webhooks.batching.buffer-size |
int |
1000 |
firefly.webhooks.batching.providers |
Map<String, BatchConfig> |
new HashMap<>() |
The firefly.webhooks.compression namespace is bound by CompressionProperties.java. Nested configuration is declared in the linked class. Defaults are the field initializers.
| Setting | Java type | Source default |
|---|---|---|
firefly.webhooks.compression.enabled |
boolean |
false |
firefly.webhooks.compression.min-size |
int |
1024 |
firefly.webhooks.compression.algorithm |
CompressionAlgorithm |
CompressionAlgorithm.GZIP |
firefly.webhooks.compression.level |
int |
6 |
The firefly.webhooks.retry namespace is bound by RetryProperties.java. Nested configuration is declared in the linked class. Defaults are the field initializers.
| Setting | Java type | Source default |
|---|---|---|
firefly.webhooks.retry.defaults |
RetryConfig |
new RetryConfig() |
firefly.webhooks.retry.providers |
Map<String, RetryConfig> |
new HashMap<>() |
The firefly.webhooks.security namespace is bound by WebhookSecurityProperties.java. Nested configuration is declared in the linked class. Defaults are the field initializers.
| Setting | Java type | Source default |
|---|---|---|
firefly.webhooks.security.max-payload-size |
long |
1048576 |
firefly.webhooks.security.validate-payload-size |
boolean |
true |
firefly.webhooks.security.validate-provider-name |
boolean |
true |
firefly.webhooks.security.provider-name-pattern |
String |
"^[a-z0-9-]+$" |
firefly.webhooks.security.enable-ip-whitelist |
boolean |
false |
firefly.webhooks.security.ip-whitelist |
Map<String, List<String>> |
new HashMap<>() |
firefly.webhooks.security.enable-request-validation |
boolean |
true |
firefly.webhooks.security.allowed-methods |
List<String> |
List.of("POST") |
firefly.webhooks.security.require-content-type |
boolean |
true |
firefly.webhooks.security.allowed-content-types |
List<String> |
List.of( "application/json", "application/x-www-form-urlencoded" ) |
Property-based wiring conditions found in this module:
name = "firefly.cache.redis.enabled", havingValue = "true", matchIfMissing = false. RedisConnectivityHealthIndicator.java.name = "firefly.webhooks.batching.enabled", havingValue = "true". WebhookBatchingServiceImpl.java.name = "firefly.webhooks.compression.enabled", havingValue = "true". WebhookCompressionServiceImpl.java.name = "firefly.webhooks.metadata-enrichment.enabled", havingValue = "true", matchIfMissing = true. WebhookMetadataEnrichmentServiceImpl.java.
Public API and extension points¶
| Type | Contract and responsibility |
|---|---|
WebhookProcessingService |
Service interface for processing webhook events. |
WebhookValidator |
Validator for webhook requests. |
WebhookSecurityProperties |
Configuration properties for webhook security and validation. |
WebhookBatchingService |
Service for batching webhook events before publishing to Kafka. |
DeadLetterQueueService |
Service for publishing rejected webhooks to the Dead Letter Queue (DLQ). |
Related components¶
| Related component | Why it belongs nearby |
|---|---|
| Webhooks Library | Group incoming webhook contracts, ingestion logic, HTTP service, processing extensions, and generated SDK. |
| Webhook Management Platform - Interfaces | Share the provider-neutral inbound webhook request and response DTOs. |
| Starter Core | Assemble core infrastructure conventions for WebClient, actuator, logging, configuration, and service discovery. |
| Common EDA Library | Publish and consume events through a common envelope and transport-independent APIs. |
| Common Cache Library | Use a common cache API with a local Caffeine default and pluggable distributed providers. |
| Observability | Provide a common metrics, tracing, health, and context-propagation foundation for framework components. |
Build and test¶
Use Java 25. From the repository root, build this component with its required dependencies:
git clone https://github.com/fireflyframework/fireflyframework-jafly.git
cd fireflyframework-jafly
./mvnw -pl :fireflyframework-webhooks-core -am verify
./mvnw -pl :fireflyframework-webhooks-core -am install
verify runs the selected projects' tests. install makes the current build available in your local Maven repository.
Representative test sources:
- WebhookEventMapperTest.java.
- WebhookMetricsServiceTest.java.
- DeadLetterQueueServiceTest.java.
- WebhookCompressionServiceTest.java.
- WebhookMetadataEnrichmentServiceTest.java.
- WebhookValidatorTest.java.
Test fixture¶
The shouldRecordMultipleProcessingTimesAndCalculateStatistics test demonstrates one concrete behavior. Excerpt from WebhookMetricsServiceTest.java. The test class supplies its fixtures and imports.
@Test
@DisplayName("Should record multiple processing times and calculate statistics")
void shouldRecordMultipleProcessingTimesAndCalculateStatistics() {
String providerName = "slack";
metricsService.recordProcessingTime(providerName, Instant.now().minusMillis(100));
metricsService.recordProcessingTime(providerName, Instant.now().minusMillis(200));
metricsService.recordProcessingTime(providerName, Instant.now().minusMillis(300));
Timer timer = meterRegistry.find("firefly.webhooks.processing.time")
.tag("provider", providerName)
.timer();
assertThat(timer).isNotNull();
assertThat(timer.count()).isEqualTo(3);
// Total time should be at least 600ms (100 + 200 + 300)
assertThat(timer.totalTime(TimeUnit.MILLISECONDS)).isGreaterThanOrEqualTo(600);
}
Continue the application¶
Use the Webhook Management Platform - Web Application guide for the next part of this integration. The runnable submission/query service is in Getting started.