242 lines
4.6 KiB
Markdown
242 lines
4.6 KiB
Markdown
# Evercatch Java SDK
|
|
|
|
Official Java SDK for [Evercatch](https://evercatch.dev) — 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
|
|
|
|
```xml
|
|
<dependency>
|
|
<groupId>dev.evercatch</groupId>
|
|
<artifactId>evercatch-java</artifactId>
|
|
<version>1.0.0</version>
|
|
</dependency>
|
|
```
|
|
|
|
### Gradle
|
|
|
|
```gradle
|
|
implementation 'dev.evercatch:evercatch-java:1.0.0'
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```java
|
|
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`:
|
|
|
|
```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`:
|
|
|
|
```yaml
|
|
evercatch:
|
|
api-key: ec_live_abc123
|
|
```
|
|
|
|
An `EvercatchClient` bean is registered automatically — inject it wherever you need it:
|
|
|
|
```java
|
|
@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:
|
|
|
|
```java
|
|
@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()`:
|
|
|
|
```java
|
|
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
|
|
|
|
```bash
|
|
# Maven
|
|
mvn clean package
|
|
|
|
# Run tests
|
|
mvn test
|
|
|
|
# Gradle
|
|
./gradlew build
|
|
|
|
# Run tests
|
|
./gradlew test
|
|
```
|
|
|
|
---
|
|
|
|
## Publishing
|
|
|
|
### Maven Central
|
|
|
|
```bash
|
|
# Build, sign, and stage
|
|
mvn clean deploy -P release
|
|
|
|
# Release from staging
|
|
mvn nexus-staging:release
|
|
```
|
|
|
|
### GitHub Packages
|
|
|
|
```bash
|
|
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](https://git.psmattas.com/Evercatch) 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.
|