Plugin Channel Providers
Build vendor-neutral notification channels with SDK v2, scoped HTTP, addresses, OAuth and delivery tracking.
Delivery pipeline
A channel plugin adds a delivery method to the normal notification pipeline. Core does not select a preferred provider. Acme Notify below is fictional; the three fixtures demonstrate integration patterns, not installable reference packages.
- The notification type, company settings, locks and personal preferences determine logical channels through
NotificationChannelResolver. SendNotificationrecords and delivers each recipient/channel independently.emailmaps to Laravelmail;in_appmaps todatabaseandbroadcast. Plugin channel names pass through unchanged.RegistryBackedNotificationChannelselects an active provider: matching subject warehouse first, then an unscoped provider, ordered byis_defaultand ID. If saved providers exist but none applies, delivery is suppressed.- The host resolves the address, checks channel opt-out, renders the channel template and calls the driver in its package/provider execution scope.
- The bridge records the returned message ID and metadata. Typed temporary failures queue only that channel again. Signed callbacks later update the same communication log.
Driver disable/uninstall makes persisted provider rows unavailable. Queued deliveries mark existing logs suppressed when the driver disappears. Other channels continue. Re-enabling a package restores its registration; saved configuration remains encrypted.
Existing built-in notifications
Registering a driver does not add the channel to existing notification-type defaults or enable delivery automatically. Installed plugin channels appear in the notification settings catalogue. An administrator must explicitly select the logical channel in company notification settings; personal preferences can then narrow the selected channels. Disabled or uninstalled drivers are unavailable.
Use GET /api/v1/notification_settings to discover type IDs and available channels, then PUT /api/v1/notification_settings with the complete desired channel list. For example:
{"notification_settings":[{"notification_type_id":42,"channels":["database","card"]}]}
For types with both internal and external audiences, set audiences.internal.channels and audiences.external.channels independently, alongside each audience's recipient rules. An empty list disables that audience's channels. Shared webhook destinations must be appropriate for the selected audience.
The built-in notification catalogue lists keys and original core defaults. This opt-in applies to notifications using the common dispatch pipeline. Dedicated authentication mail, digest mail, customer communication delivery and the fixed-path notifications listed there retain their dedicated delivery paths. A direct provider test or a synthetic envelope labelled with a type key proves transport handling, not execution of that type's native trigger. Plugins must not intercept authentication mail or import private framework services to bypass this boundary.
SDK v2 driver contract
public function key(): string;
public function channel(): string;
public function label(): string;
public function configSchema(): array;
public function resolveConfig(): array;
public function addressField(): ?ChannelAddressFieldData;
public function send(ChannelSendData $payload): ChannelSendResult;
public function test(TestChannelProviderData $data): ChannelTestResultData;
The registration key, manifest key and key() must agree. Keys are vendor-prefixed dotted identifiers such as acme.card. The logical channel is a slug such as card. Registration rejects another driver for the same logical channel. Multiple provider rows for the same driver are supported.
The bridge supplies the selected row's decrypted configuration; resolveConfig() is a fallback for drivers without a saved row and normally returns []. Drivers must not query host models. ChannelSendData carries subject (not title), body, data, config, recipientAddress, communicationLogId and providerId, plus the notifiable type and ID. Production type-based delivery uses the bridge inside SendNotification; ChannelProviderRegistry::send() is a separate low-level queued driver call, not a substitute for the preference/logging pipeline.
Return new ChannelSendResult(messageId: 'remote-id', meta: ['accepted' => true]) for success. Supported lifecycle statuses are the host communication-log registry keys. The host validates each result before persisting it; an unknown status is a permanent protocol failure and is never written to a log or automatically resent. For temporary errors, return status: 'failed', retryAfter: 30 or throw ChannelDeliveryException(permanent: false, retryAfter: 30). For permanent rejection use permanent: true. Core never parses provider error codes. Retry delay is clamped to 1–3600 seconds, with at most three channel retries. Other throwables also retry only the failed channel using the existing 30, 120 and 600 second backoff; only explicitly permanent failures bypass retries. Exhausted retries invoke the job failure handler. A driver may put limits, segment counts and other non-secret diagnostics in meta. Never include tokens or complete secret URLs.
Manifest and configuration
package: acme/notify
name: Acme Notify
version: 1.0.0
signals_version: "^1.0"
sdk: "^2.0"
network: [api.example.com, auth.example.com]
channel_drivers:
- key: acme.card
channel: card
label: Acme Notify Cards
config_fields:
- name: endpoint
type: url
required: true
secret: true
extends_network: true
routes:
- path: callback
method: POST
auth: verifier:callback
Manifests declaring any channel driver must explicitly include sdk: "^2.0"; omission fails validation with an SDK upgrade hint.
Register the driver with $registrar->channelDriver('acme.card', AcmeCardDriver::class). Runtime configSchema() returns ChannelConfigFieldData values. Supported types include string, password, email, integer, URL, select, boolean and textarea. A field can declare required, secret, help, placeholder, default, options and additional validation rules. Select options map submitted values to display labels. Every manifest field with type: select must also include a non-empty options map, even when the PHP configSchema() supplies the same options. Omitting manifest options prevents installation.
config_fields:
- name: mode
type: select
options:
direct: Direct message
webhook: Saved webhook
secret: false
extends_network: false
Manifest config_fields accepts these objects or historical field-name strings; objects communicate security-sensitive capabilities for review. At registration, field names, types, secret flags and extends_network flags must match PHP configSchema() exactly. A historical name-only field means type string, secret false, extends_network false. Missing fields or mismatches stop registration before the registry is modified.
new ChannelConfigFieldData(
key: 'endpoint', label: 'Webhook URL', type: 'url',
required: true, secret: true, extends_network: true,
help: 'Paste the HTTPS URL supplied for this workspace.',
);
Provider config is encrypted at rest. API/UI responses mask declared secrets; masked placeholders preserve saved values. The save action validates the merged values against the driver schema. The stored manifest is the single authority for type: url, extends_network: true network grants at save time and send time. PHP configSchema() still supplies form fields and ordinary validation; it cannot independently grant a host. Saving rejects HTTP, private/reserved destinations and invalid DNS through WebhookUrlGuard. At delivery, only the exact saved URL host extends this package's allowlist, only within that provider's execution scope. Redirects remain disabled and the host/DNS guard still runs before transport. There are no wildcard or suffix grants.
test() receives a free-form recipient validated against addressField(); the admin label and input type come from that descriptor. Tests send real requests when run outside Http::fake; they are not simulations. providerId identifies the saved provider for scoped network extensions.
Addresses and linking
Return null from addressField() for a fixed destination webhook. Otherwise return ChannelAddressFieldData(label, inputType: 'text'|'tel'|'email', help, placeholder, validationRules). Rules are ordinary Laravel rules, including a driver-supplied regex. Core has no provider address formats.
Resolution is: the selected provider’s user_channel_addresses row for a user/account, then their generic row (channel_provider_id: null), explicit external recipient_addresses[channel], optional ResolvesChannelAddress::resolveAddress(ChannelRecipientData), then skipped_no_address. Implement NormalizesChannelAddress::normalizeAddress() when needed. Invalid addresses are skipped before sending. ChannelRecipientData gives type and ID; PluginContext::read('accounts', $id) exposes declared safe account fields, including phones and emails, under manifest data permissions. Use $context->remember('identity:'.$id, 600, fn () => ...) for expiring provider lookups. Background code has no implicit authenticated operator: request only permitted background-readable fields.
The person's notification settings page renders the descriptor. Optional VerifiesChannelAddress::sendVerification($address, $code) enables the code flow. Codes are hashed, expire after ten minutes, permit five attempts and are throttled per connection. Verification executes in the selected provider scope: PluginContext::providerConfig() supplies that provider’s config and the exact saved operator host is available. For a generic address, verification uses the default unscoped provider when one is available. Changing the address clears verification and connection metadata. An administrator linking another person's address through the API records it as verified. Repeated authorized API updates provide bulk linking without a separate import format. The provider's Only Send to Verified Addresses policy requires verified personal links. Explicit external addresses and contact lookups use the separate Require Verification for External Recipients setting, which defaults off. Turning it on skips external recipients until they have a verified personal link; there is no implicit verification claim for arbitrary supplied addresses.
External contacts with an account use the same resolver. Direct recipients without an account pass addresses in the payload. Type consent and $context->optOut($channel, $address, $optedOut) are enforced before delivery. A reply handler maps its own opt-in/opt-out vocabulary to this API; core knows no special keywords.
Authentication and HTTP
All requests use PluginContext::forPackage('acme/notify')->http(). request() returns a guarded Laravel pending request: withToken(), withBasicAuth(), withHeaders(), asForm() and attach() support bearer/API keys, Basic auth, custom headers, JSON, forms and multipart. Keep credential hosts in network; use encrypted provider config or encrypted manifest settings for secrets.
For OAuth, implement HasChannelOAuth::oauth(): ChannelOAuthData. Declare token, authorization, identity and revoke endpoints plus scopes and config credential keys. Endpoint URLs may contain {config_key} placeholders: values from the saved provider config are URL-encoded before substitution. Every resulting HTTPS endpoint is checked against the manifest allowlist or that provider’s operator-host grant and the destination guard. OAuth descriptor evaluation, connection, token exchange/refresh and revocation run inside the selected provider scope. The host renders Connect/Disconnect controls for provider installation and personal connections, owns the callback route, validates expiring one-use state bound to the signed-in actor and uses S256 PKCE. Provider tokens are encrypted on the provider; personal tokens are encrypted in address metadata. Identity responses are normalized and validated before linking. Use identity_from: 'token_response' and identityPath: 'connected_user.id' to extract identity directly from the token response without an identity request; the default endpoint source uses identityUrl. Personal connections are unique per user, channel and provider; a separate partial unique index preserves one generic row per user/channel. Settings shows a Connect action for each active provider. New OAuth connections are provider-specific, and token refresh/disconnect select that provider’s connection. Existing rows migrate unchanged as generic rows; historical OAuth metadata remains bound to its original provider. Deleting a provider removes its scoped personal connections while generic rows remain. $context->oauth()->token($providerId, $userId) returns a cached token and refreshes within sixty seconds of expiry. Omit $userId for the installation token. A descriptor without an authorization endpoint uses the client-credentials grant. Disconnect calls the declared revoke endpoint before clearing credentials.
Templates
Declare a notification template for any installed logical channel. Cross-plugin channels are checked during activation, so a notification package can use a channel package without owning its driver. output_type is text or json. JSON templates must be valid JSON with merge fields inside string values; the renderer substitutes values and encodes the result so quotes/newlines cannot alter the structure. Provider-specific size limits belong in the driver.
The selected channel's subject/body reach ChannelSendData; the ordinary body remains in data['email_body']. Saving a new warehouse template requires a channel from the dynamic registry. Editing an existing template may retain its saved channel even while its driver is unavailable; this preserves historical templates without making that channel a core delivery option. Warehouse communication templates retain their output_type and take precedence when configured; otherwise plugin manifest templates apply, then the notification's default body. Workflow customer communication uses its pinned, rendered communication template. Structured manifest output is identified by data['output_type'].
Inbound routes and tracking
Register named verifiers with $registrar->verifier('callback', $verifier) and a declared route with $registrar->routes('POST', 'callback', function (PluginContext $context, Request $request) { ... });. The URL is /api/v1/plugins/acme/notify/callback. Routes exist only while enabled. Manifest auth is verifier:name, api or public. API auth requires an active signed-in API user and an explicit route ability, such as plugins:write; the host checks that token ability before dispatch. Handlers must still apply operation-specific authorization. Callback payload validation belongs to the plugin.
Public routes have a visible admin warning, are audited and permit ten requests per IP/minute. API routes permit sixty per IP/minute. Signature-verified routes default to 600 per minute per provider and route, configurable with manifest rate_limit from 1 to 6000. Invalid signatures do not consume the verified budget. Pass ?provider_id=123 on the callback URL to select an active provider owned by the package; the handler then receives that provider’s exact-host grant. Without a provider ID the verified budget is package/route scoped and no operator-host grant is available. Callback senders may not retry: size limits for expected receipt bursts. Failed signatures do not execute the callback. Audit entries contain package/path/auth, not request secrets.
Generic verifier building blocks are HmacBodyVerifier (algorithm, signature prefix, optional timestamp header, replay window, separator and signed-message prefix), HmacUrlVerifier (URL plus sorted parameters, configurable algorithm/encoding) and HeaderSecretVerifier. All compare signatures in constant time. Self-hosted installations behind TLS-terminating proxies must configure Laravel TrustProxies for the trusted proxy addresses and forwarded scheme/host headers so URL signatures use the original scheme and host. Each generic verifier accepts either a secret string or a closure evaluated inside the callback’s provider scope. Read the selected provider config and fall back to a declared plugin setting:
$registrar->verifier('callback', new HeaderSecretVerifier(
fn (): string => $context->providerConfig()['signing_secret']
?? $context->setting('signing_secret', ''),
));
Declare provider secret fields as secret in both PHP and the manifest. Callback URLs carry provider_id; another provider’s secret cannot authenticate that callback. Without a provider scope, providerConfig() returns an empty array, so the plugin setting is used. The same closure pattern works for body and URL HMAC verifiers. Plugins compose these without implementing cryptography. Timestamp windows limit expired requests; use your event/message ID for replay-safe effects within the window.
A verified callback can call $context->trackDelivery('message', $messageId, 'delivered'). It only matches messages recorded against this package's provider/channel and queues a tracking update. Return values indicate whether a matching message was found. Alternatively register a DeliveryTrackingResolver, optionally implementing VerifiesInboundRequest; without it the existing default HMAC verifier applies. See Inbound delivery tracking.
Declare/register an event with workflow: true and use $context->emit('acme.message.interaction', $payload) for inbound replies or buttons. The normal event/workflow permission and payload contracts still apply.
Capability matrix and Acme Notify walkthroughs
| Pattern | Authentication | Recipient/linking | Templates and callbacks | Fixture |
|---|---|---|---|---|
| Workspace card | Secret operator URL; exact-host extension | Fixed destination, no personal address | JSON card; optional signed callback | webhook-card-channel |
| Identity bot | OAuth installation, automatic refresh/revoke | Per-user OAuth or manual user ID; cached lookup seam | Interactive events; rate-limit hints | bot-token-channel |
| Addressed message | Basic auth; API key/header variants use the same HTTP seam | Generic address rule and optional code verification | Message ID tracking; opt-in/out reply | api-key-message-channel |
Acme Notify workspace card
Declare a secret URL field with extends_network, save it in a warehouse-scoped provider and return no address field. In send(), decode the JSON body and post it using the context. Return the response ID. Do not offer a destination override if the operator URL already fixes its destination.
$context = PluginContext::forPackage('acme/webhook-card-channel');
$response = $context->http()->post($payload->config['endpoint'], [
'card' => json_decode($payload->body, true, 512, JSON_THROW_ON_ERROR),
]);
return new ChannelSendResult(messageId: $response->json('id'));
The full SDK-only driver, registration and manifest are in the webhook-card-channel example. A new package uses its own Composer autoloader and the generated SDK stubs for static analysis; fixtures are not published packages.
Acme Notify identity bot
Declare the authority and API hosts. Return a ChannelOAuthData descriptor, connect the installation in provider settings, and let each person connect in their preferences. The identity endpoint supplies a user ID. During send(), obtain $context->oauth()->token($payload->providerId) and use withToken(). Map a provider throttle to ChannelSendResult(status: 'failed', retryAfter: $seconds). Register a verifier-gated interactive route that emits a declared workflow event. See the bot-token-channel example.
Acme Notify addressed message
Declare the address rule and VerifiesChannelAddress; send the supplied verification code with the same guarded HTTP client. Use asForm()->withBasicAuth($accountId, $secret) for outbound messages. Return the provider message ID, register a signed callback and call trackDelivery() for receipts. Map inbound reply actions to optOut(..., true|false). Consent is keyed by package, channel and address. The migration copies source channel/address opt-outs to each installed manifest that declares that channel, including disabled plugins. Rows with no known owner remain unassigned for operator reconciliation; they are preserved rather than granted to an unrelated future package. See the api-key-message-channel example.
Workflow sends
Send Notification (notifications.send) chooses a type, recipients and variables. With no channels restriction, the normal resolver fans out to that type's effective internal and plugin channels. An optional Send Only on These Channels restriction comes from the live registry and cannot bypass company settings, locks, personal preferences or consent.
Recipients include normal recipient resolver rules, a user rule with user_id, or an expression rule whose context path contains an account ID/list. include_external permits account contacts. Custom type keys create workflow.custom.<key> types when the draft is saved; admins then manage them with other notification types. Existing Notify Team and Send Customer Communication steps remain supported with dynamic channels.
Simulation resolves channel/address without sending. Missing plugin overrides produce builder/API/MCP warnings and suppressed runtime logs. Each queued delivery retains workflow evidence and later message IDs/status in its communication log. Retries remain isolated by recipient/channel.
Upgrading to SDK v2
The application requirement remains signals_version: "^1.0"; the plugin SDK requirement is independently sdk: "^2.0". Explicit prior-major constraints are rejected with an upgrade message. Update every driver and regenerate package analysis stubs.
Before:
public function send(ChannelSendData $payload): void { /* transport */ }
After:
public function addressField(): ?ChannelAddressFieldData { return null; }
public function send(ChannelSendData $payload): ChannelSendResult
{
// Perform the guarded request here.
return new ChannelSendResult(messageId: $remoteId);
}
Void/null delivery results are no longer accepted. Replace any built-in address format assumption with driver-declared rules. Keep provider-specific parsing and limits inside your package.
Tests
Use the SDK test harness, Http::fake() and Http::preventStrayRequests(). Exercise the normal notification job, not just send(): assert the address, template, selected warehouse, log message ID, retry isolation and disabled behavior. Callback tests must cover invalid signatures, opt-out and receipt ownership; OAuth tests cover state reuse, encryption, refresh and revoke. Run these cases in your package test suite with the SDK test harness.
The minimal example-channel fixture also uses only SDK APIs. See Channel Provider Registry, Plugin Manifest and Channel Providers.
Shared connection engine
Channel OAuth uses the shared connection authorization engine through a channel adapter. Existing GET connect routes, state, identity linking and token storage remain unchanged. For independent integration credentials, see Plugin Connections.
Provider-dependent address fields
Delivery and saved-provider self-tests evaluate addressField() within the selected provider scope, so PluginContext::providerConfig() can distinguish addressed delivery from a fixed webhook. Unscoped driver listings and tests of unsaved candidate configuration have no saved provider configuration; return a sensible default descriptor there and validate the candidate configuration in test(). Do not cache provider-dependent metadata between calls.