PushizoDocs
SDK guides

PHP SDK

pushizo/pushizo-php — PHP ≥ 8.1, only ext-curl and ext-json; notifications, users, events, webhook signature verification, journeys, and the entire public API. Laravel example included.

pushizo/pushizo-php is for server-side use only; Guzzle isn't required (the transport can be swapped via TransportInterface), and it works with XAMPP.

Installation and initialization

composer require pushizo/pushizo-php
# If Packagist is unreachable, install directly from the GitHub repository:
# composer config repositories.pushizo vcs https://github.com/pushizo/pushizo-php && composer require pushizo/pushizo-php
use Pushizo\Client;

$hs = new Client([
    'api_key' => getenv('PUSHIZO_API_KEY'),   // hs_live_…
    'app_id' => getenv('PUSHIZO_APP_ID'),     // used when a call doesn't pass one
    'base_url' => 'https://api.pushizo.com',     // local: http://localhost:4000
    'timeout' => 30,
    'max_retries' => 3,                          // 300 ms / 1 s / 3 s for 429/5xx
    'auto_idempotency_key' => true,
]);

Sending notifications

$result = $hs->notifications->create([
    'idempotency_key' => "order-{$order->id}",
    'target' => ['include_aliases' => ['external_id' => [(string) $user->id]]],
    'headings' => ['tr' => 'Siparişiniz yola çıktı', 'en' => 'Your order has shipped'],
    'contents' => ['tr' => '…', 'en' => '…'],
    'url' => "https://pushizo.com/orders/{$order->id}",
    'data' => ['order_id' => (string) $order->id],
]);
$messageId = $result['id'];

$hs->notifications->get($messageId);
$hs->notifications->list(['limit' => 50, 'status' => 'completed']);
$hs->notifications->cancel($messageId);
$hs->notifications->deliveries($messageId, ['limit' => 100]);

Email, SMS, and notification inbox

$hs->notifications->create([
    'idempotency_key' => "shipped-{$order->id}",
    'target' => ['include_aliases' => ['external_id' => [(string) $user->id]], 'channels' => ['email', 'sms']],
    'contents' => ['tr' => 'Siparişin kargoda', 'en' => 'Your order shipped'], // SMS body
    'email_subject' => 'Your order is on its way',
    'email_mjml' => $mjml,                       // or 'email_body' (ready-made HTML)
    'email_preheader' => 'Your tracking number is inside',
    'email_from_name' => 'Store',
    'email_from_address' => 'no-reply@pushizo.com',
    'sms_from' => 'STORE',
    'add_to_inbox' => true,
    'inbox_ttl' => 7 * 86400,
]);

Users, subscriptions, events, channels

$hs->users->upsert(['external_id' => 'user_42', 'tags' => ['plan' => 'pro'], 'language' => 'tr']);
$hs->users->getByExternalId('user_42');
$hs->users->update('external_id', 'user_42', ['tags' => ['plan' => 'free']]);
$hs->users->addAliases('external_id', 'user_42', ['crm_id' => 'C-1']);
$hs->users->addSubscription('external_id', 'user_42', ['channel' => 'email', 'token' => 'a@b.c']);
$hs->users->delete('external_id', 'user_42');

$hs->subscriptions->update('sub_…', ['opted_in' => false]);
$hs->subscriptions->setOwner('sub_…', 'user_42');

$hs->events->send([[ 'external_id' => 'user_42', 'name' => 'purchase', 'properties' => ['sku' => 'A1'], 'value' => 49.9, 'occurred_at' => date(DATE_ATOM) ]]);

$hs->channels->list(); $hs->channels->validate('android_push');
$hs->apps->list(); $hs->organization->usage(['days' => 30]);

Suppression list

$page = $hs->suppressions->list(['channel' => 'email', 'reason' => 'bounce', 'limit' => 50]);
foreach ($page['data'] as $row) { echo $row['value_masked'], ' ', $row['reason'], PHP_EOL; }
$row = $hs->suppressions->create(['channel' => 'sms', 'value' => '+905321234567', 'reason' => 'manual']);
$hs->suppressions->delete($row['id']);

Identity verification

$hash = Client::identityHash(getenv('PUSHIZO_SDK_SECRET'), (string) $user->id);
// Return it as JSON; the client SDK uses it with login(externalId, identityHash).

Webhook signature

$payload = file_get_contents('php://input');            // raw body
$header  = $_SERVER['HTTP_PUSHIZO_SIGNATURE'] ?? null;
try {
    $events = Pushizo\Webhook::constructEvents($payload, $header, getenv('HS_WEBHOOK_SECRET'));
} catch (Pushizo\WebhookSignatureException $e) {
    http_response_code(400);
    exit($e->reason);
}
foreach ($events as $event) { /* deduplicate using $event['id'] */ }
http_response_code(204);

Details: Webhooks.

Journeys

$journey = $hs->journeys->create(['name' => 'Post-purchase']);
$hs->journeys->saveDraft($journey['id'], ['graph' => ['nodes' => $nodes, 'edges' => $edges], 'settings' => ['re_entry' => ['mode' => 'never']]]);
$published = $hs->journeys->publish($journey['id']); // ['journey', 'version', 'issues']
$result = $hs->journeys->triggerRun($journey['id'], ['external_id' => 'u-1', 'context' => ['order_id' => 'o-42']]);
$hs->journeys->stats($journey['id'], ['version' => $published['version']]);

Lifecycle: pause, resume, archive, duplicate; updateNode, versions, exitRun.

All resources

The SDK covers every public operation (coverage check in tests/run.php): organization, apps, notifications (history, exportEvents, estimate), users (getIdentity, export, search), subscriptions (getUserIdentity, updateByToken), events, channels, suppressions, webhooks, segments, templates (copyToApp), campaigns (variantStats, selectWinner), journeys, inAppMessages, inbox, preferences, analytics (requestText for CSV), exports, imports (createFromFile, multipart), apiKeys (rotate). For paginated endpoints, use $hs->paginate(...).

Errors

use Pushizo\PushizoException;
try { … } catch (PushizoException $e) {
    $e->status; $e->errorCode; $e->requestId; $e->details; $e->isRetryable();
}

Retry policy

Retries use exponential backoff (0.3 / 1 / 3 s; the Retry-After header is honored when present) and run at most max_retries times. To avoid double-processing requests that aren't safe to repeat on the server, the rule depends on the HTTP method:

ConditionGET, HEAD, OPTIONS, PUT, DELETEPOST, PATCH
429RetriedRetried (the request was rejected before processing)
5xx, timeout, connection dropped after sendingRetriedOnly with an Idempotency-Key
Request never sent (cURL COULDNT_RESOLVE_HOST, COULDNT_CONNECT, timeout before the connection was established → Pushizo\ConnectionException)RetriedRetried
Other 4xxNot retriedNot retried

On a 5xx or a network error after sending, the server may have processed the request; retrying a POST/PATCH without a key can produce a duplicate notification or record. notifications->create and users->upsert generate an automatic UUID when no key is given (unless automatic keys are disabled), so these two calls are safe to retry. If you want another POST/PATCH call to be retried as well, pass the key yourself: $hs->request('POST', '/v1/apps/{appId}/events', [], $body, ['idempotency_key' => "evt-$id"]) or $hs->users->upsert($body, null, "crm-$id"). Retries send the same key; the API answers a repeat with the same key within 24 hours with the original response. A custom TransportInterface must throw ConnectionException when the connection can't be established, and PushizoException (status 0) for network errors after the request has been sent.

Laravel

examples/php-laravel: a service provider (singleton Client), a facade, config/pushizo.php, a controller for identity hash / tag / event endpoints, and an idempotent queue job.

On this page