evercatch-java/README.md

Evercatch Java SDK

Official Java SDK for Evercatch — webhook infrastructure platform.

---

Tech Stack

Layer	Technology
Language	Java 11+
HTTP client	OkHttp 4
JSON	Gson
Build	Maven / Gradle
Spring Boot	Auto-configuration (optional)

---

Installation

Maven

<dependency>
    <groupId>dev.evercatch</groupId>
    <artifactId>evercatch-java</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'dev.evercatch:evercatch-java:1.0.0'

---

Quick Start

import dev.evercatch.EvercatchClient;
import dev.evercatch.model.*;
import java.util.List;

EvercatchClient client = new EvercatchClient("ec_live_abc123");

// Create a destination
Destination dest = client.createDestination(
    CreateDestinationRequest.builder()
        .name("Production")
        .url("https://myapp.com/webhooks")
        .providers(List.of("stripe", "sendgrid"))
        .eventTypes(List.of("payment.*", "email.delivered"))
        .build()
);
System.out.println("Created: " + dest.getId());

// List events
List<Event> events = client.listEvents(
    ListEventsRequest.builder()
        .provider("stripe")
        .limit(50)
        .build()
);
System.out.println("Events: " + events.size());

// Check usage
Usage usage = client.getUsage();
System.out.println("Plan: " + usage.getPlan());
System.out.println("Events this month: " + usage.getEventsThisMonth() + "/" + usage.getEventsLimit());

---

API Reference

Destinations

Method	Description
createDestination(request)	Register a new webhook destination
listDestinations()	List all destinations
getDestination(id)	Get a destination by ID
deleteDestination(id)	Delete a destination

Events

Method	Description
listEvents(request)	List events with optional filters
getEvent(id)	Get an event by ID
replayEvent(eventId, destinationIds)	Replay an event (Studio+ only)

Account

Method	Description
getUsage()	Get current account usage statistics

---

Spring Boot Integration

Add the dependency, then set your API key in application.properties:

evercatch.api-key=ec_live_abc123
# Optional: override the default API base URL
# evercatch.base-url=https://api.evercatch.dev/v1

Or in application.yml:

evercatch:
  api-key: ec_live_abc123

An EvercatchClient bean is registered automatically — inject it wherever you need it:

@Service
public class WebhookService {

    private final EvercatchClient evercatch;

    public WebhookService(EvercatchClient evercatch) {
        this.evercatch = evercatch;
    }

    public void process(String eventId) throws EvercatchException {
        Event event = evercatch.getEvent(eventId);
        // ...
    }
}

Override the auto-configured bean by declaring your own:

@Bean
public EvercatchClient evercatchClient() {
    return new EvercatchClient("ec_live_abc123", "https://custom-host/v1");
}

---

Error Handling

All methods throw EvercatchException (a checked exception). The status code is available via getStatusCode():

try {
    client.replayEvent(eventId, List.of(destId));
} catch (EvercatchException e) {
    if (e.getStatusCode() == 402) {
        System.out.println("Upgrade to Studio to replay events.");
    } else {
        throw e;
    }
}

---

Building from Source

# Maven
mvn clean package

# Run tests
mvn test

# Gradle
./gradlew build

# Run tests
./gradlew test

---

Publishing

Maven Central

# Build, sign, and stage
mvn clean deploy -P release

# Release from staging
mvn nexus-staging:release

GitHub Packages

mvn deploy
# or
./gradlew publish

---

Requirements

• Java 11 or higher
• Maven 3.6+ or Gradle 7.0+

---

Branching & Commits

All work follows the Evercatch contribution guide defined in the org README.

Branch format: EC-ID-short-description Commit format: EC-00: type(scope): message

See Evercatch Org README for full conventions.

---

CI/CD

Automated via Jenkins. Merges to main trigger staging deployments.

Pipeline	Status
Build
Lint
Test

---

License

Copyright © 2026 Evercatch. Proprietary and confidential. Unauthorised distribution is strictly prohibited.