Skip to main content

​
Notifizz PHP SDK reference

notifizz/php is the PHP SDK for tracking events. It exposes a single track() method, a hashed-token helper for widget auth, and ships on Packagist.

​
TL;DR

  • new NotifizzClient($authSecretKey, $sdkSecretKey) — two-argument constructor (no webhookSigningSecret, since the PHP SDK doesn’t expose enrichers).
  • $client->track($eventName, $properties = [], $idempotencyKey = null) — emits one event; rethrows the underlying Guzzle exception after retries.
  • Each track() retries twice (1s, then 2s) before bubbling the last exception.
  • The enricher subsystem is Node-only today — PHP backends consume enriched data normally, but cannot host enrichers.

​
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')
);
ParameterTypeDescription
$authSecretKeystringUsed by generateHashedToken() for widget backend-token auth.
$sdkSecretKeystringUsed as the Bearer token on the tracking API and posted in the body.

​
$client->track($eventName, $properties = [], $idempotencyKey = 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

ParameterTypeDefaultDescription
$eventNamestring—Canonical event name. Must match the event you registered in the dashboard.
$propertiesarray[]Associative array of event data.
$idempotencyKey?stringnull (random hex)Caller-supplied dedupe key. Set this when the same logical emit may be retried.

​
Behaviour

  • Posts { eventName, properties, sdkSecretKey, idempotencyKey } to POST /v1/events/track.
  • 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.

​
$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');
ParameterTypeDescription
$userIdstringThe 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://eu.api.notifizz.com/v1']);
OptionDefaultDescription
baseUrlhttps://eu.api.notifizz.com/v1Base URL for all SDK API calls.

​
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 — Node-only today

The enricher subsystem (registering server-side resolvers that the orchestrator calls back via HMAC-signed webhooks) ships only with the Node SDK today. A PHP backend can still consume enriched data normally — campaigns receive enriched inputs the same way regardless of where the enricher is hosted. If your campaigns need server-side enrichment, host the enrichers from a Node service alongside your PHP application. PHP parity is on the roadmap. See the enrichers protocol reference for the wire format if you decide to implement an enricher endpoint manually in PHP.

​
Error handling

track() rethrows the last Guzzle exception after exhausting retries. Wrap it where you need a custom log line: 
try {
    $client->track('order.shipped', ['orderId' => $orderId]);
} catch (\GuzzleHttp\Exception\GuzzleException $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

Tracking is a network call to POST /v1/events/track. After the SDK exhausts its 3 retry attempts, the last GuzzleHttp\Exception\GuzzleException is rethrown. Catch it explicitly — silent network failures are a foot-gun.
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.
Not via the SDK today. The enricher subsystem ships only with @notifizz/nodejs. If you need an enricher right now, host a small Node service alongside your PHP app (the enrichers tutorial walks through it). If you’re comfortable implementing the wire protocol manually, see the enrichers protocol reference — it’s a plain HTTP+HMAC contract.
Yes — track() is synchronous and the SDK retries failures with 1s + 2s delays, so a degraded backend can stall the request for up to ~3s. In Laravel, dispatch tracking from a queued job when latency matters.
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://eu.api.notifizz.com/v1.
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.

​
See also

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.