Notifizz PHP SDK reference

notifizz/php is the PHP SDK for tracking events. It exposes track(), the enricher subsystem, and a hashed-token helper for widget auth, and ships on Packagist. Node and Java carry the same surface since their 2.0.0.

TL;DR

new NotifizzClient($authSecretKey, $sdkSecretKey, $webhookSigningSecret = null, $clientOptions = []) — the third argument is required only when you call dispatch() to expose enrichers.
$client->track($eventName, $properties = [], $idempotencyKey = null, $occurredAt = null) — emits one event; rethrows the last transport error after retries.
Each track() retries twice (1s, then 2s) before bubbling the last exception.
$client->enricher($name, $options), $client->enrichProfileData($handler) and $client->dispatch($body) give PHP the same enricher surface as the Node SDK, since 2.0.0.
No ready() in PHP: the boot signal goes out inline on the first track() of the process — see Boot signal.

Installation

composer require notifizz/php

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

Constructor

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Notifizz\NotifizzClient;

$client = new NotifizzClient(
    getenv('NOTIFIZZ_AUTH_SECRET_KEY'),
    getenv('NOTIFIZZ_SDK_SECRET_KEY'),
    getenv('NOTIFIZZ_WEBHOOK_SIGNING_SECRET') ?: null, // optional, required only for dispatch()
);

Parameter	Type	Required	Description
`$authSecretKey`	`string`	yes	Used by `generateHashedToken()` for widget backend-token auth.
`$sdkSecretKey`	`string`	yes	Used as the Bearer token on the tracking API and posted in the body.
`$webhookSigningSecret`	`?string`	no	Required when calling `dispatch()` — used to verify the HMAC on incoming enricher webhooks. Without it, `enricher()` still registers locally, but `dispatch()` throws on the first invocation.
`$clientOptions`	`array`	no	Client-level config, fourth argument.

`$client->track($eventName, $properties = [], $idempotencyKey = null, $occurredAt = null)`

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.

$client->track('order.shipped', [
    'orderId' => 'ORD-4521',
    'userId'  => 'u_42',
    'carrier' => 'FedEx',
]);

// With a caller-supplied idempotency key (recommended for retried jobs):
$client->track(
    'order.shipped',
    ['orderId' => 'ORD-4521', 'userId' => 'u_42'],
    'order-shipped:ORD-4521'
);

Parameters

Parameter	Type	Default	Description
`$eventName`	`string`	—	Canonical event name. Must match the event you registered in the dashboard.
`$properties`	`array`	`[]`	Associative array of event data.
`$idempotencyKey`	`?string`	`null` (random hex)	Caller-supplied dedupe key. Set this when the same logical emit may be retried.
`$occurredAt`	`string\|\DateTimeInterface\|null`	`null` (reception time)	When the business event actually happened, if that differs from now.

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.
Rethrows the last GuzzleHttp\Exception\GuzzleException if all attempts fail.

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', ['orderId' => $orderId], occurredAt: $shippedAt);

Named arguments keep the call readable when you skip $idempotencyKey. Accepts an ISO 8601 string or any DateTimeInterface; left out of the request entirely when 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.1.0.

`$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.

$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(['baseUrl' => 'https://api.notifizz.com/v1']);

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

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.

$result = $client->identify([
    'environmentId' => $environmentId,
    'subjectA'      => ['type' => 'AppUserSubject', 'identifier' => 'u_42'],
    'subjectB'      => ['type' => 'EmailSubject', 'identifier' => 'alice@example.com'],
    'consentBasis'  => 'transactional',
]);
// $result['action'] → 'merged' | 'already_linked' | 'created_and_linked' | 'noop'

$client->detach([
    'environmentId' => $environmentId,
    'subject'       => ['type' => 'AppUserSubject', 'identifier' => 'u_42'],
]);
// action → 'detached' | 'already_detached' | 'not_found'

Key	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.

Both methods return the decoded response body as an array and throw GuzzleHttp\Exception\GuzzleException on a network failure or a >= 400 response. Unlike track(), they do not retry. Links are always declared, never inferred: Notifizz merges two identities because your code said so, not because two payloads 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.

Laravel example

In a Laravel application, register the client as a singleton:

// app/Providers/AppServiceProvider.php
use Notifizz\NotifizzClient;

public function register(): void
{
    $this->app->singleton(NotifizzClient::class, function () {
        return new NotifizzClient(
            config('services.notifizz.auth_secret'),
            config('services.notifizz.sdk_secret'),
        );
    });
}

Then inject it where you need it:

use Notifizz\NotifizzClient;

class OrderController extends Controller
{
    public function ship(Order $order, NotifizzClient $notifizz)
    {
        // ... ship the order ...

        $notifizz->track('order.shipped', [
            'orderId' => $order->id,
            'userId'  => (string) $order->user_id,
            'carrier' => $order->carrier,
        ], "order-shipped:{$order->id}");
    }
}

Enrichers

An enricher is a server-side function the Notifizz orchestrator calls to fetch live data at notification time. Your PHP service registers the handlers, exposes them on one public route, and Notifizz calls that route with an HMAC-signed webhook. Available since 2.0.0 — no Node service in the middle. Pass $webhookSigningSecret as the third constructor argument, otherwise dispatch() throws on the first call.

`$client->enricher($name, $options)`

use Notifizz\JsonSchema;

$client->enricher('fetchUser', [
    '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(),
    'cache' => ['ttl' => 3600],
    'handler' => function (array $params) use ($users) {
        $user = $users->findById($params['userId']);
        return ['email' => $user->email, 'displayName' => $user->name];
    },
]);

Option	Type	Required	Description
`description`	`string`	no	Surfaced in the discovery response.
`input`	`array` (JSON Schema)	yes	Validated on every call; a mismatch answers `input-invalid`.
`output`	`array` (JSON Schema)	yes	Discovery only — Notifizz validates server-side.
`cache`	`false` \| `['ttl' => seconds]`	no	`false` disables caching. Omitted → the Notifizz default.
`handler`	`callable(array $params): array`	yes	Must be idempotent — the backend may retry after a network failure.

JsonSchema is a small fluent builder shipped with the SDK; a hand-written schema array works just as well. Registering the same name twice throws Notifizz\EnricherRegistrationException.

`$client->enrichProfileData($handler, $description = null, $cache = null)`

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(
    function (array $params) use ($crm) {
        $customer = $crm->lookup($params['id'] ?? null, $params['email'] ?? null);
        return [
            'name' => $customer->fullName,
            'phone' => $customer->phone,
            'customerType' => $customer->tier,
        ];
    },
    'CRM profile',
    3600, // cache TTL in seconds; pass false to never cache
);

Parameter	Type	Required	Description
`$handler`	`callable(array $params): array`	yes	Receives `['id' => ?string, 'email' => ?string]`. Both keys are optional on the way in — handle whichever you get.
`$description`	`?string`	no	Defaults to a Notifizz-supplied label.
`$cache`	`false` \| `int` (seconds) \| `null`	no	`false` never caches, an integer sets the TTL, `null` uses the Notifizz default.

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

`$client->enrichers()`

Returns the discovery view of what is registered — handy in tests.

`$client->dispatch($body)`

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

// Laravel
Route::post('/notifizz', function (Request $request) {
    return response()->json($notifizz->dispatch($request->all()));
});

dispatch() accepts the parsed body (array) 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' => ...]`	A discovery call succeeded.
`['ok' => true, 'result' => ...]`	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 \RuntimeException when no $webhookSigningSecret was passed to the constructor. NotifizzClient::signDispatchPayload($secret, $payload) produces the same HMAC, for testing a dispatch route with synthetic signed requests.

Boot signal

The Node and Java SDKs expose a ready() method: you call it once your HTTP server is listening, and a non-production environment re-runs discovery on the spot. The PHP SDK has no ready() — and does not need one, because a PHP process does not stay up between requests. Instead, the SDK sends a best-effort boot signal inline, once per process, on the first track() call. It is fire-and-forget with a short timeout (1 s to connect, 2 s total) and never fails your request. It announces that the SDK key is alive; it does not ask for a re-discovery. The practical consequence, and the only one worth remembering:

	Node / Java	PHP
When the signal goes out	On `ready()`, at the moment the dispatch route starts serving	Inline, on the first `track()` of the process
Asks for an immediate re-discovery	Yes, in non-production environments	No
A newly added enricher or event property appears	Right away	On the next periodic discovery pass

So after adding an enricher to a PHP service, expect the dashboard to pick it up on the next pass rather than instantly. Nothing to call, nothing to configure.

Error handling

track() throws once it gives up. Catch \Throwable — the exception class depends on the failure mode:

Failure	Exception	Retried
Network failure (host unreachable, connection reset)	`GuzzleHttp\Exception\ConnectException`	yes, twice
`5xx` from the API, after three attempts	`\RuntimeException`	yes, twice
`4xx` from the API (auth, validation)	`\RuntimeException`, immediately	no — retrying would let the server’s idempotency replay mask the rejection behind a misleading `2xx`
A declared event schema is violated, with the client in strict validation mode	`Notifizz\TrackRejectedException`	n/a — nothing is sent

try {
    $client->track('order.shipped', ['orderId' => $orderId]);
} catch (\Throwable $e) {
    Log::error('notifizz track failed', [
        'orderId' => $orderId,
        'message' => $e->getMessage(),
    ]);
    throw $e;
}

The full error catalogue (including HTTP status mappings) is in error catalogue.

FAQ

What exception does a failed `track()` throw?

It depends on the failure — a network failure surfaces the Guzzle ConnectException, an API rejection a \RuntimeException. Catch \Throwable and look at the message; the table in Error handling lists the four cases. Handle it explicitly either way — 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, retry middleware). Use a deterministic key derived from your domain — "order-shipped:{$orderId}" is better than bin2hex(random_bytes(16)) from outside the SDK, which generates a new key per attempt and defeats the dedupe.

Can I host an enricher from my PHP 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 there a `ready()` method like in Node and Java?

No, and PHP does not need one — the process does not stay up between requests. The boot signal goes out inline on the first track() of the process instead, and it does not request an immediate re-discovery. A newly added enricher is picked up on the next periodic discovery pass. See Boot signal.

Is `track()` blocking?

Yes — track() is synchronous, and the SDK adds 1 s + 2 s of backoff between its three attempts. It does not set a response timeout of its own, so the network wait itself is bounded only by your PHP and cURL configuration: a hung backend holds the request. In Laravel, dispatch tracking from a queued job when latency matters — and never call it 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(['baseUrl' => '...']) after construction. The SDK reads the option on every track() call. Use it 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. Use Laravel’s queue or a Symfony Messenger transport to fire many events in parallel; 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 PHP SDK Reference

Notifizz PHP SDK reference

TL;DR

Installation

Constructor

`$client->track($eventName, $properties = [], $idempotencyKey = null, $occurredAt = null)`

Parameters

Behaviour

Event time (`occurredAt`)

`$client->generateHashedToken($userId)`

`$client->config($opts)`

Audience identity

What the action means

Laravel example

Enrichers

`$client->enricher($name, $options)`

`$client->enrichProfileData($handler, $description = null, $cache = null)`

`$client->enrichers()`

`$client->dispatch($body)`

Boot signal

Error handling

FAQ

See also

Event Tracking reference

Backend quickstart

Event Tracking overview

Notification Center widget

​Notifizz PHP SDK reference

​TL;DR

​Installation

​Constructor

​$client->track($eventName, $properties = [], $idempotencyKey = null, $occurredAt = null)

​Parameters

​Behaviour

​Event time (occurredAt)

​$client->generateHashedToken($userId)

​$client->config($opts)

​Audience identity

​What the action means

​Laravel example

​Enrichers

​$client->enricher($name, $options)

​$client->enrichProfileData($handler, $description = null, $cache = null)

​$client->enrichers()

​$client->dispatch($body)

​Boot signal

​Error handling

​FAQ

​See also

Event Tracking reference

Backend quickstart

Event Tracking overview

Notification Center widget

Notifizz PHP SDK reference

TL;DR

Installation

Constructor

`$client->track($eventName, $properties = [], $idempotencyKey = null, $occurredAt = null)`

Parameters

Behaviour

Event time (`occurredAt`)

`$client->generateHashedToken($userId)`

`$client->config($opts)`

Audience identity

What the action means

Laravel example

Enrichers

`$client->enricher($name, $options)`

`$client->enrichProfileData($handler, $description = null, $cache = null)`

`$client->enrichers()`

`$client->dispatch($body)`

Boot signal

Error handling

FAQ

See also