Search by

relaybell / relaybell-php

kb6472-oss

Official PHP server-side SDK for RelayBell web push notifications, event tracking, analytics and webhook verification.

v1.2.0 2026-10-20 17:42 UTC

This package is auto-updated.

Last update: 2026-10-20 17:43:20 UTC


README

Official server-side PHP SDK for RelayBell — send web push notifications, track behavioural events, record conversions, and read analytics from your backend.

  • PHP 7.4+, framework-free.
  • Dependency-light: only ext-curl and ext-json (both bundled with typical PHP builds).
  • PSR-4 autoloaded under the Relaybell\ namespace.

This is the server-side SDK. To collect subscribers in the browser, use the browser SDK instead — it runs on your storefront, not your server.

Installation

composer require relaybell/relaybell-php

Not published to Packagist yet? Point Composer at the directory:

{
    "repositories": [
        { "type": "path", "url": "sdks/php" }
    ],
    "require": {
        "relaybell/relaybell-php": "*"
    }
}

Quick start

<?php

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

use Relaybell\Client;
use Relaybell\RelaybellException;

$client = new Client('rb_live_xxxx');

try {
    $result = $client->send([
        'title' => 'Flash sale ends tonight',
        'body'  => '20% off everything until midnight.',
        'url'   => 'https://shop.example.com/sale',
        'icon'  => 'https://shop.example.com/icon.png',
    ]);

    echo "Queued notification {$result['notificationId']} (status: {$result['status']})\n";
} catch (RelaybellException $e) {
    fwrite(STDERR, "RelayBell error {$e->getStatusCode()}: {$e->getErrorCode()}\n");
    fwrite(STDERR, $e->getResponseBody() . "\n");
}

Configuration

// Default base URL is https://relaybell.com.
$client = new Client('rb_live_xxxx');

// Override the base URL (staging, self-hosted, etc.).
$client = new Client('rb_live_xxxx', 'http://localhost:8080');

// Tune timeouts (seconds).
$client = new Client('rb_live_xxxx', 'https://relaybell.com', [
    'timeout'        => 30, // total request timeout (default 30)
    'connectTimeout' => 10, // connection phase timeout (default 10)
]);

Authentication uses the HTTP header Authorization: Bearer <API_KEY>, applied automatically to every request.

API

send(array $notification): array

POST /api/v1/notifications — send or schedule a push. title is required.

$client->send([
    'title'              => 'Back in stock',
    'body'               => 'The item on your wishlist is available again.',
    'url'                => 'https://shop.example.com/p/123',
    'icon'               => 'https://shop.example.com/icon.png',
    'image'              => 'https://shop.example.com/hero.jpg',
    'badge'              => 'https://shop.example.com/badge.png',
    'actions'            => [
        ['action' => 'view', 'title' => 'View item'],
    ],
    'requireInteraction' => true,
    'tag'                => 'restock-123',
    'segmentId'          => 'seg_abc',
    'filters'            => ['country' => 'US'],
    'sendAt'             => '2026-07-06T09:00:00Z', // ISO 8601 for scheduling
    'ttl'                => 86400,                   // seconds
    'perTimezone'        => true,
    'localTime'          => '09:00',                 // "HH:MM"
    'ab'                 => [
        'b' => ['title' => 'Restocked!', 'body' => 'Grab it before it sells out.'],
    ],
]);
// => ['ok' => true, 'notificationId' => 'ntf_...', 'status' => 'queued']

track(string $event, array $opts = []): array

POST /api/v1/events — track a behavioural event. May trigger automations and sequence enrolments server-side.

$client->track('product_viewed', [
    'externalId'   => 'user_42',           // your ID for the subscriber
    // 'subscriberId' => 'sub_...',        // or RelayBell's subscriber ID
    'properties'   => [
        'productId' => 'sku_123',
        'price'     => 49.0,
    ],
]);
// => ['ok' => true, 'eventId' => 'evt_...', 'subscriberId' => 'sub_...',
//     'automationsTriggered' => [...], 'sequencesEnrolled' => [...]]

trackConversion($value, array $props = []): array

Convenience wrapper over track() that emits a purchase event with a monetary value in its properties — the same event the browser SDK's trackConversion() sends. It counts as a conversion (the value is credited to the last notification that subscriber received) and cancels pending cart reminders and journeys set to stop on purchase. externalId / subscriberId in $props are lifted out and used for subscriber attribution; all other keys become event properties. Before 1.1.0 this method sent an event named conversion.

$client->trackConversion(129.99, [
    'externalId' => 'user_42',
    'orderId'    => 'ord_789',
    'currency'   => 'USD',
]);
// Emits event "purchase" with properties { value: 129.99, orderId, currency }.

stats(): array

GET /api/v1/stats — account analytics.

$stats = $client->stats();
// => ['subscribers' => 12345,
//     'totals' => ['sent' => ..., 'clicks' => ..., 'ctr' => ...,
//                  'conversions' => ..., 'revenue' => ...],
//     'notifications' => [ ... ]]

listNotifications(array $params = []): array

GET /api/v1/notifications — your sends, newest first, 25 a page. Filters: from / to (days, "YYYY-MM-DD"), status (one, or a list: draft, scheduled, queued, held_for_review, sending, sent, failed, canceled — without it, everything except drafts), q (search in titles and texts), limit (1–100), cursor and tz.

$page = $client->listNotifications(['status' => ['sent', 'failed'], 'from' => '2026-10-01', 'limit' => 50]);
foreach ($page['items'] as $n) {
    echo $n['id'], ' ', $n['title'], ' ', $n['status'], ' ', $n['clicked'], PHP_EOL;
}
while ($page['nextCursor'] !== null) {
    $page = $client->listNotifications(['status' => ['sent', 'failed'], 'from' => '2026-10-01', 'limit' => 50, 'cursor' => $page['nextCursor']]);
}

getNotification(string $id): array

GET /api/v1/notifications/:id — one notification with its report: ['notification', 'funnel', 'devices', 'variants', 'languages', 'errors', 'revenue', 'currency', 'sendBody']. An id that isn't one of this website's throws a RelaybellException with status 404.

Identity verification

When your site tells relaybell who a signed-in visitor is (externalId, often their email), sign that id on your server with Client::userHash(). Once your project requires verified ids (dashboard → Settings → Developer → User ID verification), relaybell ignores an id that comes without a valid hash, so nobody can pretend to be one of your customers to get their notifications.

use Relaybell\Client;

// Your project's identity secret (Settings → Developer). Keep it on the server only.
$secret = getenv('RELAYBELL_IDENTITY_SECRET');
$email  = $user->email;
$hash   = Client::userHash($secret, $email); // no network request, no client needed
$safe   = JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT; // safe inside <script>
?>
<script>
  RelayBell.init({
    projectId: 'proj_xxxx', apiBase: 'https://relaybell.com',
    externalId: <?= json_encode($email, $safe) ?>, userHash: <?= json_encode($hash) ?>
  });
  // or, after the visitor signs in: RelayBell.identify(externalId, userHash);
</script>

Client::userHash(string $secret, string $externalId): string returns the lowercase hex HMAC-SHA256 of the id keyed with the secret — the same as hash_hmac('sha256', $externalId, $secret). Sign the id exactly as you pass it to the browser. If you rotate the secret, update your server's copy: hashes made with the old secret stop working at once.

Verifying webhooks

relaybell signs every webhook it sends to your server. Relaybell\Webhook::verify() checks the X-Relaybell-Webhook-Signature header and returns the event — or throws Relaybell\WebhookVerificationException — with no network request:

use Relaybell\Webhook;
use Relaybell\WebhookVerificationException;

$raw = file_get_contents('php://input'); // the exact bytes relaybell signed
try {
    $event = Webhook::verify(
        $raw,
        getallheaders(),                     // or $_SERVER, or a PSR-7 $request->getHeaders()
        getenv('RELAYBELL_WEBHOOK_SECRET')   // whsec_…, shown when you add the webhook
        // , 300                             // tolerance in seconds (default 5 minutes)
    );
} catch (WebhookVerificationException $e) {
    http_response_code(401);             // $e->getReason() says why
    exit;
}
$deliveryId = $_SERVER['HTTP_X_RELAYBELL_DELIVERY'] ?? ''; // the same on every retry: handle each one once
http_response_code(200);                 // answer within 10 seconds, then do the work
// $event['event'] e.g. "notification.clicked", $event['data'] e.g. ['notificationId' => ..., 'variant' => null]

Webhook::verify(string $payload, array $headers, $secret, int $tolerance = 300, bool $allowLegacy = false): array fails closed; getReason() is one of:

Reason When
missing_secret The secret is empty, null or false (an unset getenv()) — it never verifies without one
missing_signature No X-Relaybell-Webhook-Signature header
malformed_signature The header has no valid t / v1
timestamp_out_of_tolerance The signature is more than $tolerance seconds old (or ahead): a replayed request
signature_mismatch Wrong secret, or the body was changed (or decoded and re-encoded)
invalid_payload The body isn't a JSON object

The older X-Relaybell-Signature header (a signature of the body only, with no timestamp) is still sent, but is accepted only with $allowLegacy = true and only when the request has no v1 signature. relaybell retries failed deliveries for about 10 hours, so the same event can arrive more than once: de-duplicate by X-Relaybell-Delivery. See Webhooks.

Error handling

Every non-2xx response throws Relaybell\RelaybellException. Transport failures (DNS, connection, timeout) throw the same exception with a status code of 0.

try {
    $client->send(['title' => 'Hi']);
} catch (RelaybellException $e) {
    $e->getStatusCode();   // int  — HTTP status, or 0 for transport errors
    $e->getErrorCode();    // ?string — the API's "error" code, e.g. "invalid_api_key"
    $e->getResponseBody(); // string  — raw, undecoded response body
    $e->getResponseData(); // ?array  — decoded JSON body, if any
}

The API returns errors as JSON { "error": "code" } with a normal HTTP status. getErrorCode() extracts that code for you.

Browser SDK

The server SDK is for backend calls only. To subscribe visitors and fire client-side events, load the browser SDK on your storefront:

<script src="https://relaybell.com/relaybell-sdk.js"></script>
<script>
  RelayBell.init({ projectId: 'proj_xxxx', apiBase: 'https://relaybell.com' });

  // Also available in the browser:
  // RelayBell.identify(externalId, userHash)
  // RelayBell.track(event, properties)
  // RelayBell.trackConversion(value, props)
  // RelayBell.unsubscribe()
  // RelayBell.isSupported()
</script>

Requirements

  • PHP >= 7.4
  • ext-curl, ext-json

Changelog

1.2.0

  • New Relaybell\Webhook::verify($payload, $headers, $secret, $tolerance = 300) checks the timestamped X-Relaybell-Webhook-Signature header (constant-time, hash_equals) and returns the event; it throws Relaybell\WebhookVerificationException (getReason()), including when the secret is empty. The older X-Relaybell-Signature is accepted only with $allowLegacy = true. See Verifying webhooks.
  • New listNotifications(array $params = []) and getNotification(string $id) for GET /api/v1/notifications and /:id.

1.1.0

  • trackConversion() now sends a purchase event (it sent conversion before), the same event as the browser SDK and the WordPress plugin. Purchases recorded from your server now cancel cart reminders and journeys set to stop on a purchase. Its arguments haven't changed. If you built an automation or journey on the conversion event, switch it to purchase.
  • New Client::userHash($secret, $externalId) for identity verification: signs a visitor's id on your server so the browser SDK can prove it. No network request. See Identity verification.

License

MIT