Java SDK

meridian-java - the official Java/Kotlin client: Maven/Gradle setup, builders, CompletableFuture support, and webhook verification.

Last updated September 8, 20261 min readEdit page

On this page

The official Java client for Java 11+, available on Maven Central as dev.meridian:meridian-java. Immutable builders, CompletableFuture async variants, and a WebhookSignature verifier.

Installation

MavenXML

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

Gradle (Kotlin DSL)kotlin

implementation("dev.meridian:meridian-java:1.0.0")

Gradle (Groovy)groovy

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

Initialization

Client.javaJava

import dev.meridian.MeridianClient;

MeridianClient client = MeridianClient.builder()
    .apiKey(System.getenv("MERIDIAN_API_KEY"))
    .timeout(Duration.ofSeconds(30))
    .maxRetries(3)
    .build();

Methods

Projects.javaJava

Project project = client.projects().create(
    ProjectCreateParams.builder()
        .name("billing-sync")
        .region(Region.US_EAST)
        .build()
);

Project fetched = client.projects().get(project.id());

Method	Endpoint
`projects().create(params)`	`POST /projects`
`projects().get(id)`	`GET /projects/:id`
`projects().update(id, params)`	`PATCH /projects/:id`
`projects().delete(id)`	`DELETE /projects/:id`
`projects().list(params)`	`GET /projects` - `Stream<Project>`
`webhooks().create / list / deliveries / replay`	`/webhooks*`
`events().list / get`	`/events*`

Async

Every synchronous method has a …Async variant returning CompletableFuture:

Async.javaJava

client.projects()
    .createAsync(params)
    .thenAccept(project -> log.info("created {}", project.id()))
    .exceptionally(err -> {
        log.error("create failed", err);
        return null;
    });

Webhook verification

Webhook.javaJava

import dev.meridian.webhook.WebhookSignature;

Event event = WebhookSignature.verify(
    rawBody,                            // String - do NOT deserialize first
    request.getHeader("Meridian-Signature"),
    System.getenv("WEBHOOK_SECRET")
);

Errors

API failures throw MeridianException subclasses:

Exception	Status
`AuthenticationException`	401
`PermissionException`	403
`NotFoundException`	404
`ConflictException`	409
`RateLimitException` (`retryAfter()`)	429
`ApiException`	5xx

Errors.javaJava

try {
    client.projects().create(params);
} catch (RateLimitException e) {
    scheduleRetry(e.retryAfter());
} catch (MeridianException e) {
    log.error("{} {} (req {})", e.code(), e.getMessage(), e.requestId());
}

Installation

MavenXML

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

Gradle (Kotlin DSL)kotlin

implementation("dev.meridian:meridian-java:1.0.0")

Gradle (Groovy)groovy

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

import dev.meridian.MeridianClient; MeridianClient client = MeridianClient.builder() .apiKey(System.getenv("MERIDIAN_API_KEY")) .timeout(Duration.ofSeconds(30)) .maxRetries(3) .build();

Methods

Projects.javaJava

Project project = client.projects().create(
    ProjectCreateParams.builder()
        .name("billing-sync")
        .region(Region.US_EAST)
        .build()
);

Project fetched = client.projects().get(project.id());

Method	Endpoint
`projects().create(params)`	`POST /projects`
`projects().get(id)`	`GET /projects/:id`
`projects().update(id, params)`	`PATCH /projects/:id`
`projects().delete(id)`	`DELETE /projects/:id`
`projects().list(params)`	`GET /projects` - `Stream<Project>`
`webhooks().create / list / deliveries / replay`	`/webhooks*`
`events().list / get`	`/events*`

client.projects() .createAsync(params) .thenAccept(project -> log.info("created {}", project.id())) .exceptionally(err -> { log.error("create failed", err); return null; });

import dev.meridian.webhook.WebhookSignature; Event event = WebhookSignature.verify( rawBody, // String - do NOT deserialize first request.getHeader("Meridian-Signature"), System.getenv("WEBHOOK_SECRET") );

Errors

API failures throw MeridianException subclasses:

Exception	Status
`AuthenticationException`	401
`PermissionException`	403
`NotFoundException`	404
`ConflictException`	409
`RateLimitException` (`retryAfter()`)	429
`ApiException`	5xx

Errors.javaJava

try {
    client.projects().create(params);
} catch (RateLimitException e) {
    scheduleRetry(e.retryAfter());
} catch (MeridianException e) {
    log.error("{} {} (req {})", e.code(), e.getMessage(), e.requestId());
}