Laravel Livestorm Laravel Package

Getting Started

Install and wire it up

composer require livestorm/laravel-livestorm   # confirm exact vendor name in the release
php artisan vendor:publish --tag=livestorm-config

Add your API token to .env (never commit it):

LIVESTORM_API_TOKEN=your_api_token_here

The token comes from your Livestorm workspace settings (API section) and is sent as a bearer token. Confirm the required scopes for events, people, and webhooks before you start — a missing scope usually surfaces as a 403 deep inside a request rather than at boot.

Where to look first

1. config/livestorm.php — base URL, token, timeouts, and any webhook secret. This is the single source of truth for how the client behaves, and almost every "why is it doing that?" question is answered here.
2. The package's service provider — check what is bound into the container (a singleton client, a facade alias, formatters). That tells you whether you should inject an interface or resolve a concrete class.
3. The webhook controller/route the package registers, if it ships one. If it doesn't, you're writing that route yourself and the package only gives you the signature verification helper.

First useful use case

List events, then register a person against a session. That single flow exercises auth, pagination, and a write request — enough to prove the integration works before you build anything on top of it.

$events = Livestorm::events()->all();          // paginated collection
$event  = Livestorm::events()->find($eventId);

Livestorm::sessions()->create($eventId, [
    'name'       => 'Session 1',
    'started_at' => now()->addWeek()->toIso8601String(),
]);

Run it in php artisan tinker first. It's the fastest way to confirm the token and base URL are right without touching your app's HTTP layer.

Implementation Patterns

Resolve the client, don't new it

Inject the client (or its facade) so Http::fake() and config changes apply in tests. If you're building a larger feature, wrap the package in your own thin service — WebinarService, RegistrantSync — so the rest of your app doesn't import package classes directly. When a breaking change lands in 1.x, you patch one class instead of forty.

Keep the API boundary at the edges

The most durable pattern: package calls live in jobs and console commands, not in controllers. A controller dispatches SyncEventRegistrants; the job talks to Livestorm; the results land in your own tables. Webinar APIs are slow and rate-limited, and keeping them off the request path is the difference between a snappy app and a 30-second page load.

Webhooks: verify, persist, then queue

Typical flow for a Livestorm webhook handler:

Route::post('/webhooks/livestorm', function (Request $request) {
    abort_unless(
        $request->header('X-Livestorm-Signature') && Livestorm::webhooks()->verify($request),
        403
    );

    WebhookEvent::firstOrCreate(
        ['external_id' => $request->input('id')],
        ['type' => $request->input('type'), 'payload' => $request->all()]
    );

    ProcessLivestormWebhook::dispatch($request->all());

    return response()->noContent();
});

Two rules worth engraving: verify the signature before parsing anything meaningful, and return 2xx fast. Livestorm will retry on non-2xx, and retries plus a slow handler equals duplicate processing.

Idempotency everywhere

Webhook deliveries can repeat. firstOrCreate on a provider-supplied event id, or a unique index on (livestorm_event_id, livestorm_person_id), saves you from a very confusing "why did this person get two confirmation emails" bug six weeks later.

Pagination

List endpoints paginate. Use the package's iterator/each() helper rather than manually looping page numbers — if the package exposes cursor-based pagination, manual page params will silently miss records. If you're pulling a large event list on a schedule, chunk and checkpoint it rather than fetching everything every hour.

Pair it with the Livestorm webhook catalog

A polling-only integration burns rate limit and is always stale. Subscribe to session and registration events, and use the API for reconciliation (a nightly job that re-fetches anything with a stale updated_at). Polling as a backstop, webhooks as the primary signal.

Testing

Http::fake() against the documented endpoints gives you fast, deterministic tests. Assert on the outgoing request — URL, method, Authorization header, and body shape — not just the returned DTO. That's what catches a broken payload after an upgrade.

Gotchas and Tips

The token is a credential, and logs leak it

Most HTTP clients log full requests at debug level. Audit that the Authorization header is redacted in your logging stack before you point production at this. Also: rotate per-environment tokens so a staging leak doesn't touch prod data.

Rate limits are the usual first incident

Any backfill of people or sessions will hit them. Expect 429s, and configure retry-with-backoff in config/livestorm.php (or your HTTP client) rather than writing ad-hoc sleep() calls. If the package doesn't ship retry logic, wrap the client in your own decorator — a single place to add backoff, timeouts, and metrics.

Timezones will bite you

Event and session times from Livestorm are typically UTC. Store UTC, render in the user's timezone. The classic bug is a "starts at 10:00" email that's correct in one timezone and off by two hours in another — usually because someone called Carbon::parse() without a timezone and got app default.

Webhook secret and signature mismatches

Signature verification failures are almost always one of: wrong secret (staging secret in prod env), the framework middlewares modifying the body (e.g. trimming/encoding), or a proxy stripping the signature header. Log the raw body hash on failure during bring-up, then remove the logging.

Status transitions aren't guaranteed ordering

Webhook session.ended can arrive before session.started if retries reorder delivery. Treat events as observations with timestamps, not as a state machine you can apply blindly.

Version pin carefully

1.0.0 means the surface is fresh and may move. Pin with a caret constraint and read the changelog before bumping minor versions — early-life API clients often rename resource methods or reshape returned DTOs. Anything you write against package classes should be behind your own wrapper.

Extension points to know

The service provider binding is your seam for mocking, decorating (retries, logging, metrics), or swapping in a fake for local development. The published config file is your seam for base URL — point it at a mock server in feature tests or against a Livestorm sandbox if one is offered.

Don't mirror the whole API

Resist building a 1:1 Eloquent model for every Livestorm resource. Store only what your app's queries actually need — event id, name, start time, registration counts — and fetch the rest on demand. Full mirroring is a large maintenance burden that breaks on every upstream field change.