Integration guides

PHP with Laravel

Complete path for a Laravel 11 backend with drop-in files for the client, the controllers and the webhook.

php-laravel/ of the examples repo contains files that drop into a Laravel 11 app (PHP 8.3): app/Limenia/WebhookSignature.php (plain PHP), app/Limenia/LimeniaClient.php, app/Limenia/LimeniaEventHandler.php (placeholders), app/Http/Controllers/LimeniaController.php, app/Http/Controllers/LimeniaWebhookController.php, config/limenia.php and routes/limenia.php.

Setup

  1. Copy the files into your app and include the routes from routes/api.php with require __DIR__.'/limenia.php';. The api route group has no CSRF check, which the webhook needs; Laravel prefixes these routes with api, so the webhook URL is https://<your-host>/api/limenia/webhook.
  2. Put the app routes (reports, me/moderation-status, devices/request-hash, devices/check) behind your auth middleware (e.g. auth:sanctum). The webhook route has no auth middleware: the signature is the authentication.
  3. The user sets LIMENIA_API_KEY, LIMENIA_WEBHOOK_SECRET (and optionally LIMENIA_WEBHOOK_SECRET_PREVIOUS, LIMENIA_BASE_URL) in .env; config/limenia.php reads them.

Signature check

WebhookSignature::verify, called with $request->getContent(), the raw body:

PHP
public static function verify(?string $header, string $rawBody, array $secrets, ?int $now = null): void
{
    if ($header === null || $header === '') {
        throw new InvalidSignature('missing_signature');
    }
    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        $pair = explode('=', trim($part), 2);
        if (count($pair) !== 2) {
            throw new InvalidSignature('malformed_signature');
        }
        [$key, $value] = $pair;
        if ($key === 't') {
            if ($timestamp !== null) {
                throw new InvalidSignature('malformed_signature');
            }
            $timestamp = $value;
        } elseif ($key === 'v1') {
            $signatures[] = $value;
        }
    }
    if ($timestamp === null || preg_match('/\A[0-9]{1,12}\z/', $timestamp) !== 1 || $signatures === []) {
        throw new InvalidSignature('malformed_signature');
    }
    if (abs(($now ?? time()) - (int) $timestamp) > 300) {
        throw new InvalidSignature('timestamp_out_of_range');
    }
    foreach ($secrets as $secret) {
        $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
        foreach ($signatures as $signature) {
            if (hash_equals($expected, $signature)) { // constant time
                return;
            }
        }
    }
    throw new InvalidSignature('signature_mismatch');
}

The controller dedupes event IDs with the cache (Cache::has('limenia:event:'.$id), kept 3 days); a table with a unique key on the event ID is safer in production.

Complaints and reviews

Add controller actions for complaints and reviews like the report action: user from the login, Idempotency-Key, store the returned ID with the user. See Complaints and Pre-moderation reviews.