Documentation

SDK Integration Guides

SOCWarden offers SDKs for Laravel, Node.js, Python, Go and the browser. Each SDK provides three ways to track events: named arguments, raw data and a fluent builder. Pick your language below.

Installation

Terminal

composer require soc-warden/laravel-sdk

Configuration

.env

SOCWARDEN_API_KEY=sk_live_your_key_here
SOCWARDEN_ENDPOINT=https://ingest.socwarden.com

# Optional
SOCWARDEN_AUTO_CONTEXT=true    # Auto-collect request context
SOCWARDEN_QUEUE=true           # Dispatch events via queue
SOCWARDEN_LISTEN_AUTH=true     # Auto-track auth events
SOCWARDEN_BROWSER_HEADER=X-SOCWarden-Context
SOCWARDEN_TIMEOUT=5

Basic Usage

The track() method is the primary way to send events. Pass an event type and named arguments.

app/Http/Controllers/AuthController.php

use SOCWarden\Facades\SOCWarden;

// Simple event tracking with named arguments
SOCWarden::track(
    event: 'auth.login.success',
    actor: $user,
);

// With extra metadata
SOCWarden::track(
    event: 'data.exported',
    actor: $user,
    resource: 'customers',
    metadata: ['format' => 'csv', 'rows' => 15000],
);

Raw Data

Send a raw key-value object when you need full control over the payload. Useful for dynamic or computed fields.

Raw data array

use SOCWarden\Facades\SOCWarden;

// Send raw key-value data
SOCWarden::track('auth.login.success', [
    'actor_id' => $user->id,
    'actor_email' => $user->email,
]);

Fluent Builder

Chain methods for a readable, type-safe event construction. Call .send() at the end to dispatch.

Fluent Builder

use SOCWarden\Facades\SOCWarden;

SOCWarden::event('admin.settings.updated')
    ->actor($admin)
    ->meta('setting', 'billing')
    ->meta('changed_by', $admin->email)
    ->send();

Middleware Setup

Middleware auto-captures request context (IP, user-agent, path, method) so you don't have to pass it manually on every call. IP addresses are validated before sending — invalid values are silently dropped.

bootstrap/app.php

// Laravel 11+ (bootstrap/app.php)
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(
        \SOCWarden\Middleware\CaptureContext::class
    );
})

// The middleware auto-captures:
// - Client IP address
// - User-Agent string
// - Request method, path, and query
// - Browser context relay header

Auth Event Auto-Tracking

Auth event auto-tracking is enabled by default. The SDK
listens to Laravel's Login, Failed, Logout, Registered,
and PasswordReset events and tracks them automatically.

Disable with: SOCWARDEN_LISTEN_AUTH=false

Event Type Format

Event types must match: [a-z][a-z0-9]{0,29}(\.[a-z][a-z0-9_]{0,29}){1,3}

2-4 dot-separated segments. Examples:

auth.login.successauth.login.failureauth.mfa.enrolledauth.password.resetdata.exportedadmin.settings.updatedresource.updatedresource.deletedserver.ssh.login.failure

Rate Limit Handling

All SDKs automatically handle HTTP 429 responses. On rate limit, the client backs off for the Retry-After duration (default: 1 hour). During backoff, events are silently dropped. A probe request is sent every 5 minutes to check if the quota has been restored. On success, normal operation resumes immediately.

← PreviousGetting Started Next →Agent Setup