Custom integrations

Ship a first-party feed for your internal API or a niche SaaS tool by implementing an integration driver. Drivers appear under Integrations (global credentials / Connections) and attach per form as feeds.

IntegrationDriver contract

Every driver implements Bjanczak\FilamentFlexForms\Integrations\Contracts\IntegrationDriver:

Method	Purpose
`key()` / `name()` / `description()` / `category()`	Identity in Studio
`globalConfigFields()` / `connectionConfigFields()`	Panel-wide vs Connection-tier credentials
`credentialMode()`	`GlobalOnly`, `ConnectionOnly`, or `GlobalOrConnection`
`driverSchemaVersion()`	Bump when feed/connection JSON shape changes
`formFeedFields()`	Per-form options (list ID, mapping, endpoint)
`normalizeGlobalConfig()` / `normalizeFormFeed()`	Sanitize saved JSON
`isConfigured()` / `testConnection()`	Integrations rail health check
`dispatch(..., ?FlexFormIntegrationConnection $connection = null)`	Send payload on submission

Extend AbstractIntegrationDriver for shared HTTP helpers, or start from:

GenericApiIntegrationDriver — JSON POST + bearer + SSRF guard + redacted delivery meta
GenericOAuthIntegrationDriver — OAuth authorize/callback with PKCE S256 + Connections
GenericSignedWebhookDriver — HMAC-signed outbound webhooks

Register drivers (3 ways)

1. Config (explicit)

config/filament-flex-forms.php

'extensibility' => [
    'integrations' => [
        'drivers' => [
            \App\FlexForms\Integrations\AcmeCrmDriver::class,
        ],
        'discover' => [],
        'allow_override' => false,
    ],
],

2. Discovery folder

'discover' => [
    app_path('FlexForms/Integrations'),
],

3. Plugin `boot()`

FilamentFlexFormsPlugin::make()
    ->registerIntegration(\App\FlexForms\Integrations\AcmeCrmDriver::class);

Artisan scaffold

php artisan flex-forms:make-integration AcmeCrm --api
php artisan flex-forms:make-integration AcmeHub --oauth
php artisan flex-forms:make-integration AcmeHook --webhook

Creates:

app/FlexForms/Integrations/{Name}Driver.php
tests/Feature/FlexForms/{Name}DriverTest.php (skip with --no-test)

The Pest stub registers the driver and extends IntegrationDriverTestCase (key slug, credential mode, normalize helpers).

Cookbook 1 — REST list API (end-to-end)

Scaffold

php artisan flex-forms:make-integration AcmeList --api

Implement endpoint + payload

Override endpoint() (HTTPS public URL only — SSRF guarded) and buildPayload() from FieldMapper output. Optionally override testConnectionRequest() to return a health URL so Test connection performs a real GET ping.

Add the class to extensibility.integrations.drivers (or discovery).

Credentials

Open Integrations, paste the API key (encrypted at rest). For Connection-tier drivers, create a Connection instead.

Map fields on a form

Enable the feed → Advanced field mapping (email → email, transforms like trim / phone_e164). Save + publish.

Send test

Use Send test — delivery ledger shows source=sandbox with redacted secrets. Submit a live response and confirm a succeeded delivery row.

Pest

Extend IntegrationDriverTestCase and add Http::fake() coverage for a 200 dispatch and a 429 retryable failure if your driver surfaces that status.

app/FlexForms/Integrations/AcmeListDriver.php

final class AcmeListDriver extends GenericApiIntegrationDriver
{
    public function key(): string { return 'acme_list'; }
    public function name(): string { return 'Acme List'; }

    protected function endpoint($form, $submission, array $globalConfig, array $feed): string
    {
        return 'https://api.acme.example/v1/subscribers';
    }

    protected function testConnectionRequest(array $config): ?string
    {
        return 'https://api.acme.example/health';
    }

    protected function buildPayload(array $mapped, $form, $submission, array $feed): array
    {
        return [
            'email' => $mapped['email'] ?? null,
            'tags' => $mapped['tags'] ?? [],
            'source' => 'flex-forms',
        ];
    }
}

Cookbook 2 — OAuth CRM with PKCE (end-to-end)

Flex Forms OAuth Connections use authorization code + PKCE (S256) by default.

Scaffold

php artisan flex-forms:make-integration AcmeHub --oauth

Wire provider URLs

Implement getOAuthAuthorizeUrl(), getTokenUrl(), getClientId(), getClientSecret(), getOAuthScopes(). Keep usesPkce() at default true unless the provider rejects PKCE.

In the provider console set redirect URI exactly to https://your-domain/flex-forms/connections/oauth/callback.

Connect account

Integrations → Connections → Create → Connect. Redirect builds code_challenge; callback exchanges code + code_verifier (one-time cache, bound to admin user) and returns to the Connections tab.

Attach to a form

Set connection_id on the feed (Studio Connections picker). Tokens refresh via OAuthTokenManager (mutex + needs_reauth on failure).

Verify

Test connection, then Send test. Confirm deliveries never store raw client_secret / bearer tokens.

Override usesPkce(): false only for legacy providers. Prefer fixing the provider registration over disabling PKCE.

Cookbook 3 — Signed partner webhook (end-to-end)

Scaffold

php artisan flex-forms:make-integration AcmeHook --webhook

Secret

Store webhook_secret on the Connection (or global config). Outbound body is HMAC-SHA256 signed.

Feed URL

Set request_url to an HTTPS public endpoint. Private / metadata hosts are rejected (SSRF guard).

Map + Send test

Map nested fields, enable the feed, Send test, inspect the submission ledger (source=sandbox, redacted context).

Field mapping + transforms

Host transforms:

use Bjanczak\FilamentFlexForms\Integrations\Mapping\FieldMapper;

FieldMapper::extend('acme_code', fn (mixed $value): mixed => strtoupper((string) $value));

Built-ins include trim, uppercase, merge_template, split_name, phone_e164, file_url, and more — see Field mapping.

Isolation & safety checklist

Use AbstractIntegrationDriver::httpClient() (timeouts, no open redirects)
Expect delivery context to be redacted (Authorization, api_key, tokens)
Scope Connections in multi-tenant apps via modifyConnectionsEloquentQueryUsing() — Multi-tenancy
Run php artisan flex-forms:upgrade after package updates

Platform helpers (sealed)

GraphQL HTTP helpers, device-code OAuth, SAML assertion verification, inbound webhook receivers, and scheduled remote sync are first-class SDK surfaces — see Public API, Inbound webhooks, and the sections below in this cookbook.

APIs & config

Extensibility

Architecture

IntegrationDriver contract

Register drivers (3 ways)

1. Config (explicit)

2. Discovery folder

3. Plugin `boot()`

Artisan scaffold

Cookbook 1 — REST list API (end-to-end)

Cookbook 2 — OAuth CRM with PKCE (end-to-end)

Cookbook 3 — Signed partner webhook (end-to-end)

Field mapping + transforms

Isolation & safety checklist

Platform helpers (sealed)

​IntegrationDriver contract

​Register drivers (3 ways)

​1. Config (explicit)

​2. Discovery folder

​3. Plugin boot()

​Artisan scaffold

​Cookbook 1 — REST list API (end-to-end)

​Cookbook 2 — OAuth CRM with PKCE (end-to-end)

​Cookbook 3 — Signed partner webhook (end-to-end)

​Field mapping + transforms

​Isolation & safety checklist

​Platform helpers (sealed)

IntegrationDriver contract

Register drivers (3 ways)

1. Config (explicit)

2. Discovery folder

3. Plugin `boot()`

Artisan scaffold

Cookbook 1 — REST list API (end-to-end)

Cookbook 2 — OAuth CRM with PKCE (end-to-end)

Cookbook 3 — Signed partner webhook (end-to-end)

Field mapping + transforms

Isolation & safety checklist

Platform helpers (sealed)