Notifizz Java SDK reference

com.notifizz:notifizz-java is the JVM SDK for tracking events. It exposes track() overloads, the enricher subsystem, the event catalog, a hashed-token helper for widget auth, and works the same from Java or Kotlin. The package is published to Maven Central.

TL;DR

new NotifizzClient(authSecretKey, sdkSecretKey) — plus a 3-arg form taking webhookSigningSecret and a 4-arg form taking NotifizzClientOptions.
client.track(eventName, properties) — emits one event; throws IOException on transient failures after retries.
client.track(eventName, properties, idempotencyKey) — overload for retried jobs.
client.track(eventName, properties, idempotencyKey, occurredAt) — overload declaring when the business event happened (Instant or ISO 8601 String).
Each track() retries twice (1s, then 2s) before bubbling IOException.
client.enricher(name, options), client.declareEvent(name, options) and client.dispatch(body) give the JVM the same enricher and event-catalog surface as the Node SDK, since 2.0.0.
client.ready() — call it once your server is listening (Spring: on ApplicationReadyEvent), so a non-production environment re-runs discovery immediately instead of on the next periodic pass.
NotifizzClient implements Closeable — close() releases the pooled HTTP connections.

Installation

Maven
Gradle (Kotlin DSL)
Gradle (Groovy)

<dependency>
    <groupId>com.notifizz</groupId>
    <artifactId>notifizz-java</artifactId>
    <version>2.2.0</version>
</dependency>

dependencies {
    implementation("com.notifizz:notifizz-java:2.2.0")
}

dependencies {
    implementation "com.notifizz:notifizz-java:2.2.0"
}

No custom repository or credentials are required — Maven Central is used by default.

Constructor

import com.notifizz.NotifizzClient;

NotifizzClient client = new NotifizzClient(
    System.getenv("NOTIFIZZ_AUTH_SECRET_KEY"),
    System.getenv("NOTIFIZZ_SDK_SECRET_KEY")
);

Two more forms exist. Add the signing secret when this service exposes enrichers, and NotifizzClientOptions when you want a schema mode or a rejection callback:

import com.notifizz.NotifizzClient;
import com.notifizz.NotifizzClientOptions;
import com.notifizz.SchemaMode;

NotifizzClient client = new NotifizzClient(
    System.getenv("NOTIFIZZ_AUTH_SECRET_KEY"),
    System.getenv("NOTIFIZZ_SDK_SECRET_KEY"),
    System.getenv("NOTIFIZZ_WEBHOOK_SIGNING_SECRET"),
    NotifizzClientOptions.builder()
        .schemaMode(SchemaMode.STRICT)
        .onError((eventName, reason, payload) -> logger.error("notifizz rejected {}", eventName))
        .build()
);

Parameter	Type	Required	Description
`authSecretKey`	`String`	yes	Used by `generateHashedToken()` / `generateSubscribeToken()` for widget auth.
`sdkSecretKey`	`String`	yes	Used as the Bearer token on the tracking API and posted in the body.
`webhookSigningSecret`	`String`	no	Required to expose enrichers — `dispatch()` uses it to verify the HMAC on incoming webhooks. When `null`, `enricher()` and `declareEvent()` still register locally, but `dispatch()` throws `IllegalStateException`.
`clientOptions`	`NotifizzClientOptions`	no	Built with `NotifizzClientOptions.builder()`. Carries `schemaMode` (`SchemaMode.SOFT` default, `SchemaMode.STRICT`) and `onError`. `schemaMode` is overridden at boot by the `NOTIFIZZ_SCHEMA_MODE` env var.

`client.track(eventName, properties)`

Emits a single event. Notifizz resolves campaigns by eventName and runs each campaign’s orchestrator server-side to build the recipient list — there is no client-side workflow or recipient targeting.

import java.util.Map;

client.track("order.shipped", Map.of(
    "orderId", "ORD-4521",
    "userId", "u_42",
    "carrier", "FedEx"
));

`client.track(eventName, properties, idempotencyKey)`

Overload with an explicit idempotency key. Use this when the same logical emit may run twice (retry, dedupe).

client.track(
    "order.shipped",
    Map.of("orderId", "ORD-4521", "userId", "u_42"),
    "order-shipped:ORD-4521"
);

Parameters

Parameter	Type	Description
`eventName`	`String`	Canonical event name. Must match the event you registered in the dashboard.
`properties`	`Map<String, Object>`	Arbitrary key-value data passed to campaigns. `null` is treated as an empty map.
`idempotencyKey`	`String`	Caller-supplied dedupe key. `null` generates a UUID. Only on the 3- and 4-arg overloads.
`occurredAt`	`Instant` or `String`	When the business event actually happened. `null` leaves it undeclared. Only on the 4-arg overload.

Behaviour

Posts { eventName, properties, sdkSecretKey, idempotencyKey } to POST /v1/events/track — plus occurredAt when you declare one.
Sends Authorization: Bearer <sdkSecretKey> and X-Idempotency-Key: <idempotencyKey>.
Retries transient failures twice (1s, then 2s) — three total attempts.
Throws java.io.IOException if all attempts fail or the response status is >= 400.

Event time (`occurredAt`)

By default, the moment Notifizz receives an event is the moment it happened — right, when you track at the point the thing occurs. Declare the event time when the two genuinely differ: replaying a queue, flushing a batch collected offline, backfilling history.

client.track(
    "order.shipped",
    Map.of("orderId", "ORD-4521"),
    "order-shipped:ORD-4521",
    shippedAt          // java.time.Instant, or an ISO 8601 String
);

Both overloads leave the field out of the request when you pass null — an absent field tells the API that reception time is the only truth. A date in the future is refused with event/invalid-occurred-at; a 60-second tolerance absorbs client clock skew. The value feeds time-scoped resolutions server-side, so it must never claim a state that does not exist yet. Available since 2.2.0.

Kotlin

The SDK works naturally with Kotlin — the same Map.of / mapOf interop applies:

val client = NotifizzClient(
    System.getenv("NOTIFIZZ_AUTH_SECRET_KEY"),
    System.getenv("NOTIFIZZ_SDK_SECRET_KEY"),
)

client.track("order.shipped", mapOf(
    "orderId" to "ORD-4521",
    "userId" to "u_42",
))

// With idempotency key:
client.track(
    "order.shipped",
    mapOf("orderId" to "ORD-4521"),
    "order-shipped:ORD-4521",
)

`client.generateHashedToken(userId)`

Generates the SHA-256 of userId + authSecretKey. Pass it to your frontend so the Notification Center widget can authenticate in backendToken mode.

String token = client.generateHashedToken("u_42");

Parameter	Type	Description
`userId`	`String`	The user’s unique identifier — must match the `userId` you pass to the widget.

Returns — String, hex-encoded SHA-256. See backend tokens for the widget side.

`client.config(opts)`

Overrides default options. Currently only baseUrl is configurable.

client.config(Map.of("baseUrl", "https://api.notifizz.com/v1"));

Option	Default	Description
`baseUrl`	`https://api.notifizz.com/v1`	Base URL for all SDK API calls.

Declaring events

Declaring an event registers it in a catalog the orchestrator AI and the dashboard can read — schema, description and idempotency fields included, instead of properties guessed from observed payloads. Declaring is optional; tracking always works without it. Available since 2.0.0.

import com.notifizz.DeclareEventOptions;
import com.notifizz.JsonSchema;

String ORDER_SHIPPED = client.declareEvent("order.shipped", DeclareEventOptions.builder()
    .description("An order has been handed to the carrier and a tracking URL is available")
    .schema(JsonSchema.object()
        .prop("orderId", JsonSchema.string(), true)
        .prop("userId", JsonSchema.string(), true)
        .prop("carrier", JsonSchema.string(), false)
        .build())
    .idempotencyFields("orderId")
    .build());

client.track(ORDER_SHIPPED, Map.of("orderId", "ORD-4521", "userId", "u_42"));

declareEvent() returns the canonical (trimmed) event name — store it and pass it to track() so a rename stays a one-line change. client.declaredEvents() returns the discovery view for diagnostics and tests. Schemas are plain JSON Schema (Map<String, Object>). JsonSchema is a fluent builder for the common shapes; hand-built maps work just as well.

Validation modes (`SchemaMode`)

The schema mode is SDK-local. The Notifizz server never blocks a track over a declared schema — strict mode is a guard rail for dev and CI.

Case	`SchemaMode.SOFT` (default)	`SchemaMode.STRICT`
Event not declared	warn, push	no push, throws `TrackRejectedException`, `onError` invoked
Payload not matching declared schema	warn, push unchanged	no push, throws `TrackRejectedException`, `onError` invoked
All good	silent push	silent push

Set it per environment without touching code:

NOTIFIZZ_SCHEMA_MODE=strict mvn test

When idempotencyFields is declared and you pass no key, track() derives a deterministic one from those properties — a retry of the same logical event dedupes on its own. See Events for the catalog UI and the tradeoffs at a higher level.

Enrichers

An enricher is a server-side function the Notifizz orchestrator calls to fetch live data at notification time. You register one per data source, expose them on a public URL, and the backend calls them via HMAC-signed webhooks. Available on the JVM since 2.0.0. The full protocol is in the enrichers protocol reference.

`client.enricher(name, options)`

Registers an enricher on this client. Call once per enricher, before your dispatch route serves traffic.

import com.notifizz.EnricherOptions;
import com.notifizz.JsonSchema;

client.enricher("fetchUser", EnricherOptions.builder()
    .description("Live user profile from the application database")
    .input(JsonSchema.object()
        .prop("userId", JsonSchema.string().minLength(1), true)
        .build())
    .output(JsonSchema.object()
        .prop("email", JsonSchema.string(), true)
        .prop("displayName", JsonSchema.string(), true)
        .build())
    .cacheTtl(3600)
    .handler(params -> {
        User user = userRepository.find((String) params.get("userId"));
        return Map.of("email", user.email(), "displayName", user.name());
    })
    .build());

Builder method	Required	Description
`description(String)`	no	Surfaced in the discovery response and the dashboard catalog.
`input(Map)`	yes	JSON Schema. Used for discovery and runtime validation of incoming params.
`output(Map)`	yes	JSON Schema. Discovery only — Notifizz validates results server-side.
`cacheTtl(long)` / `cacheTtl(String)`	no	Declares the cache TTL — a number of seconds, or a duration string. Omitted → the Notifizz default of 1 hour.
`noCache()`	no	Notifizz never caches this enricher’s responses.
`handler(EnricherHandler)`	yes	`Map<String, Object> handle(Map<String, Object> params)`. Must be idempotent — the backend may retry after a network failure.

client.enrichers() returns the discovery view of what is registered — handy in tests.

`client.enrichProfileData(handler)`

Registers the system enricher that feeds the Audience profile panel in the dashboard. It differs from enricher() on three points: it takes the reserved name notifizz:profileResolver (hidden from the enricher catalog), its input is fixed to { id, email } — one user per call, no batch — and its output is free-form.

client.enrichProfileData(params -> Map.of(
    "name", "Alice Martin",
    "phone", "+33 1 23 45 67 89",
    "customerType", "VIP"
));

// With an explicit description and cache TTL in seconds:
client.enrichProfileData("CRM profile", 3600, params -> Map.of(/* ... */));

Whatever fields you return are rendered in the profile panel — there is no schema to declare on the way out.

`client.dispatch(body)`

The body-only webhook entry point. Your controller is a one-liner:

@PostMapping("/notifizz")
public Map<String, Object> dispatch(@RequestBody Map<String, Object> body) {
    return client.dispatch(body);
}

dispatch() accepts the parsed body (Map) or a raw JSON String. It verifies the HMAC over the inner payload, rejects stale timestamps (anti-replay, ±5 min), and routes discovery versus enricher execution.

Result body	When
`{ ok: true, result: <discovery payload> }`	A discovery call succeeded — enrichers and declared events.
`{ ok: true, result: <handler return> }`	An execute call ran the registered handler.
`{ ok: false, error: { code, message } }`	Anything failed. Full code table in the enrichers protocol reference.

Errors are encoded inside the body, never thrown across the dispatch boundary — your framework writes 200 unconditionally and Notifizz translates error.code back into a typed domain error. That is what keeps the controller one line. dispatch() throws IllegalStateException if no webhookSigningSecret was passed to the constructor. NotifizzClient.signDispatchPayload(secret, payload) produces the same HMAC, for testing a dispatch route with synthetic signed requests.

Audience identity

identify() links two Subjects to the same Audience — the mechanism that makes an application user and an email address the same person. detach() puts a Subject back into an Audience of its own. Available since 2.0.0.

Map<String, Object> result = client.identify(Map.of(
    "environmentId", environmentId,
    "subjectA", Map.of("type", "AppUserSubject", "identifier", "u_42"),
    "subjectB", Map.of("type", "EmailSubject", "identifier", "alice@example.com"),
    "consentBasis", "transactional"
));
// result.get("action") → "merged" | "already_linked" | "created_and_linked" | "noop"

client.detach(Map.of(
    "environmentId", environmentId,
    "subject", Map.of("type", "AppUserSubject", "identifier", "u_42")
));
// action → "detached" | "already_detached" | "not_found"

Field	Required	Description
`environmentId`	yes	The environment the Subjects live in.
`subjectA` / `subjectB`	yes (`identify`)	`{ type, identifier }`. Types: `AppUserSubject`, `EmailSubject`, `WebSubject`, `WebhookSubject`.
`subject`	yes (`detach`)	Same shape, the one Subject to unlink.
`consentBasis`	yes (`identify`)	`transactional` or `marketing` — the legal basis recorded for the link.
`expiresAt`	no (`identify`)	ISO 8601. A daily job unlinks attachments once they pass it.

What the action means

`identify` action	Meaning
`merged`	The two Subjects were in different Audiences; the second Audience was absorbed into the first.
`already_linked`	They were already the same person. Nothing moved — the assertion and its consent basis are still journaled.
`created_and_linked`	At least one Subject did not exist yet; it was created, then linked.
`noop`	Reserved in the SDK’s type; the API does not return it today.

`detach` action	Meaning
`detached`	The Subject was moved into a new Audience of its own.
`already_detached`	It was the only Subject on its Audience — nothing to unlink.
`not_found`	No Subject of that type with that identifier in that environment.

Links are always declared, never inferred: Notifizz merges two identities because your code said so, not because a payload looked similar. In a production environment, an EmailSubject on a known disposable domain is refused (disposable_email_domain); outside production the call succeeds and the response carries a warnings entry instead. Both calls throw IOException on a network failure. An HTTP error status is not turned into an exception: the response body is decoded and returned as-is, so check for an action key before trusting the map. Neither call retries.

`client.ready()`

Signals that this service’s dispatch endpoint is mounted and serving its current set of enrichers and declared events. Call it once, when your HTTP server is listening — in Spring Boot, from an ApplicationReadyEvent listener.

@Component
public class NotifizzReadySignal {

    private final NotifizzClient client;

    public NotifizzReadySignal(NotifizzClient client) {
        this.client = client;
    }

    @EventListener(ApplicationReadyEvent.class)
    public void onReady() {
        client.ready();
    }
}

Why a dedicated call rather than the boot signal the constructor already sends: the constructor runs before your enricher() and declareEvent() registrations and before the server binds its port, so at that moment the discovery endpoint cannot answer truthfully yet. ready() fires at the one instant the catalog is actually servable.

Aspect	Behaviour
Return	`void` — the signal goes out on a daemon thread, so startup is never blocked.
Failure	Never throws, never propagates. One retry after 2 s on a transient failure; a `4xx` stops immediately.
Idempotent	Yes. Safe on every boot, every reload.
In production	Effectively a no-op — only non-production environments re-run discovery on this signal.

The payoff is the local loop. In a non-production environment, the signal asks Notifizz to re-run discovery immediately, so an enricher or event property you just added shows up without a dashboard refresh and without waiting for the periodic pass.

Cross-language: ready() exists in the Node and Java SDKs. The PHP SDK has no equivalent — see PHP: boot signal.

Lifecycle

All calls share one pooled HTTP client with bounded timeouts — connect 2 s, response 5 s, pool checkout 2 s (since 2.1.0). Instantiate NotifizzClient once and keep it: a client per request throws the pool away every time and pays a fresh TLS handshake. NotifizzClient implements Closeable; close() releases the pool. A long-lived singleton can skip it — the JVM reclaims the connections at exit — but a managed bean should not: Spring picks close() up as the destroy method automatically.

@Bean(destroyMethod = "close")
public NotifizzClient notifizzClient() {
    return new NotifizzClient(authKey, sdkKey);
}

Error handling

track() declares throws IOException. Wrap it where you need a custom log line:

try {
    client.track("order.shipped", Map.of("orderId", orderId));
} catch (IOException e) {
    logger.error("notifizz track failed for order " + orderId, e);
    throw new RuntimeException(e);
}

After three failed attempts, the last IOException is rethrown — the SDK does not silently swallow failures. The full error catalogue (including HTTP status mappings) is in error catalogue.

FAQ

Why does `track()` throw `IOException`?

Tracking is a network call to POST /v1/events/track. After the SDK exhausts its 3 retry attempts, the underlying IOException (or a wrapped one for >= 400 HTTP statuses) is rethrown. Always handle it — silent network failures are a foot-gun.

Should I generate the idempotency key myself?

Yes when the same logical emit may be retried (queued jobs, scheduler, retry middleware). Use a deterministic key derived from your domain — order-shipped:{orderId} is better than UUID.randomUUID() from outside the SDK, which generates a new key per attempt and defeats the dedupe.

Can I host an enricher from my Java service?

Yes, since 2.0.0. Register handlers with client.enricher(name, options), pass a webhookSigningSecret to the constructor, and expose client.dispatch(body) on a public route — see Enrichers above. No Node service in the middle.

Is `track()` blocking?

Yes — track() is synchronous. Since 2.1.0 the wait is bounded: three attempts, each capped at 2 s to connect and 5 s for the response, plus the 1 s + 2 s backoff between them. A fully degraded backend can therefore stall the calling thread for roughly 24 s. Run it on an ExecutorService or a virtual thread when latency matters — and never inside a database transaction, where the wait would hold a connection hostage.

How do I configure a custom base URL for staging?

Call client.config(Map.of("baseUrl", "...")) after construction. The SDK reads the option on every track() call. Use this for local mocks, regional endpoints, or staging environments — production is https://api.notifizz.com/v1.

Can I batch several events in one call?

Not today. Each track() call is one event. Fire them in parallel with an executor when batching matters; idempotency keys ensure retries dedupe at the backend.

Event Tracking reference

HTTP wire format, idempotency contract, error shapes.

Backend quickstart

Send your first event in under five minutes.

Event Tracking overview

Cross-language feature matrix.

Notification Center widget

Display the notifications your events drive.

Get started

Concepts

Use cases

SDKs

AI & MCP

Environments

Plans & usage

Monitor delivery

Glossary

Notifizz Java SDK Reference

Notifizz Java SDK reference

TL;DR

Installation

Constructor

`client.track(eventName, properties)`

`client.track(eventName, properties, idempotencyKey)`

Parameters

Behaviour

Event time (`occurredAt`)

Kotlin

`client.generateHashedToken(userId)`

`client.config(opts)`

Declaring events

Validation modes (`SchemaMode`)

Enrichers

`client.enricher(name, options)`

`client.enrichProfileData(handler)`

`client.dispatch(body)`

Audience identity

What the action means

`client.ready()`

Lifecycle

Error handling

FAQ

See also

Event Tracking reference

Backend quickstart

Event Tracking overview

Notification Center widget

​Notifizz Java SDK reference

​TL;DR

​Installation

​Constructor

​client.track(eventName, properties)

​client.track(eventName, properties, idempotencyKey)

​Parameters

​Behaviour

​Event time (occurredAt)

​Kotlin

​client.generateHashedToken(userId)

​client.config(opts)

​Declaring events

​Validation modes (SchemaMode)

​Enrichers

​client.enricher(name, options)

​client.enrichProfileData(handler)

​client.dispatch(body)

​Audience identity

​What the action means

​client.ready()

​Lifecycle

​Error handling

​FAQ

​See also

Event Tracking reference

Backend quickstart

Event Tracking overview

Notification Center widget

Notifizz Java SDK reference

TL;DR

Installation

Constructor

`client.track(eventName, properties)`

`client.track(eventName, properties, idempotencyKey)`

Parameters

Behaviour

Event time (`occurredAt`)

Kotlin

`client.generateHashedToken(userId)`

`client.config(opts)`

Declaring events

Validation modes (`SchemaMode`)

Enrichers

`client.enricher(name, options)`

`client.enrichProfileData(handler)`

`client.dispatch(body)`

Audience identity

What the action means

`client.ready()`

Lifecycle

Error handling

FAQ

See also