README

Porta receives JSON webhooks through integrations managed in Filament. Each integration controls authentication, response behavior, and payload transforms before an accepted webhook is dispatched to an application-defined handler through Laravel's queue.

Features

Filament resource for configuring and testing webhook integrations.
Header, query-string, or unauthenticated webhook endpoints.
JSONPath-based mapping, dropping, moving, casting, trimming, date conversion, renaming, and insertion.
Configurable empty, identity-only, or webhook-detail responses and HTTP status codes.
Queued processing with persisted status, error details, retry actions, and delivery history.
Handler registry for routing transformed payloads into application code.
Optional tenancy and policy-backed integration management.

Requirements

PHP 8.4 or later
Laravel 13
Filament 5
A queue worker when using an asynchronous queue connection

Installation

composer require phpinnacle/porta
php artisan vendor:publish --tag="phpinnacle-porta-migrations"
php artisan migrate

Publish the configuration when the navigation or tenancy defaults need to change:

php artisan vendor:publish --tag="phpinnacle-porta-config"

Registering handlers

use App\Jobs\SyncContact;
use PHPinnacle\Porta\Handler;
use PHPinnacle\Porta\PortaPlugin;

$panel->plugin(
    PortaPlugin::make()->handle(
        new Handler(
            type: 'crm.contact.updated',
            label: 'CRM contact updated',
            invoker: function (array $payload) {
                SyncContact::dispatch($payload);
            },
            example: '{"contact":{"id":"example-id"}}',
        ),
    ),
);

The invoker receives the transformed payload. Handler types are stable identifiers: an integration selects one type, and the queued job resolves that type from the registry when processing begins.

Receiving webhooks

Create an integration in Filament, select a registered handler, and configure its authentication, response, and transforms. The edit page shows the generated endpoint:

POST /webhook/{integration-id}

Porta stores the raw body and request headers, then dispatches ProcessWebhook after the surrounding database transaction commits. Rolled-back creation does not dispatch a job; retries follow the same commit boundary. Run the application's queue worker so scheduled webhooks can reach their handlers:

php artisan queue:work

Only JSON payloads are currently supported. Transforms run in their configured order before the handler is invoked. A JSON payload containing {"test":"test"} exercises endpoint authentication and returns immediately without creating a webhook record.

Transforms use PHPinnacle\Jason\JsonQuery, with no Galbar dependency. JSONPath selectors support dot and quoted property names such as $['meta.version'], array indexes (including negative indexes), unions, slices, wildcards, filters, and recursive selections. Filters support comparisons, logical operators, root references, membership, and regular expressions.

PHP lists, including [], represent JSON arrays; other PHP arrays represent JSON objects. Property selectors match only objects; integer indexes match only lists. Numeric property names require property syntax such as $['2'] or $.2. Wildcards select children of either container type.

DROP removes the selected nodes by path, so equal values elsewhere remain untouched. Removing array items preserves a list with consecutive indexes. DROP $ clears the payload to []; a missing path leaves it unchanged. MOVE writes selected values to its destination in selection order, creating missing properties in existing objects and missing indexes in lists, and then applies the same source deletion. Missing intermediate branches are lists ([]); MOVE cannot create object parents or write properties into lists. Ensure destination parents have the required types: source deletion still occurs when a destination does not match. If several values target one destination, the last value wins. Invalid JSONPath syntax fails when the transform runs.

Integration access is controlled by IntegrationPolicy. Webhook records may contain credentials or personal data from request headers and bodies, so restrict the Filament resource, logs, and database access and define an appropriate retention policy.

Development

Run the repository checks from the monorepo root:

composer lint
composer test

Changelog and license

See CHANGELOG. Released under the MIT License.

phpinnacle / porta

Package info

Security

Statistics