SIGNALS Docs
Reader View

Webhook Event Registry

Contract for registering outbound webhook event names, grouped discovery metadata, and metering weights.

Overview

App\Services\Api\WebhookEventRegistry is the runtime registry for outbound webhook event discovery metadata and metering weights.

Core binds it as a singleton in AppServiceProvider and seeds it from the canonical event catalogue — EventRegistry::names('webhook'), i.e. every entry in config/events.php with webhook: true that is not system_protected. The event names are therefore derived, not hand-maintained here: add a webhook event by adding it to config/events.php. The catalogue is intentionally large, so this page documents the event-definition contract and discovery helpers rather than duplicating the entire event reference. For the exhaustive shipped list, use the Webhooks API reference.

EventRegistry is the generic name authority: its consumer-specific discovery methods decide which events are visible to REST subscriptions, audit bridges, and delivery, and this registry only decorates that webhook-visible slice.

WebhookEventRegistry::CORE_EVENT_NAMES is a generated mirror of that derived list, kept only for static contexts that cannot reach the container; an architecture ratchet asserts the two are identical, so the mirror cannot drift.

WebhookEventRegistry provides webhook metadata. It derives labels, groups, and metering weights from the shared registry, preserves custom metadata registered through its metadata helpers, and discovers direct EventRegistry plugin registrations dynamically. Direct plugin registration uses the shared EventDefinition contract; WebhookEventRegistry::register() is also a complete registration path that creates a webhook-visible plugin definition before retaining its metadata override. Neither path grants API, workflow, or general plugin visibility.

Public surface

Method Purpose
register() Register one event definition
registerMany() Register multiple event definitions atomically
decorate() Attach metadata to a name the catalogue already carries
get() Return one event definition or null
all() Return the full keyed event map
groups() Return grouped discovery metadata
names() Return the flat list of currently registered event names
has() Check whether an event name is registered
weight() Return the event's outbound metering weight
schemaVersion() Return the event's payload contract version (default 1)
deliverySchema() Return the HTTP delivery envelope schema for a registered event

This metadata registry does not publish a separate registered-value interface. Its current framework contract is the typed public surface on this page plus the documented registration shape and runtime behavior below.

Accepted registration shape

Each event is identified by its registration name. Core uses dotted names such as account.created, settings.updated, and document.pdf_generated, but the registry does not require event names to be non-empty or dotted. Duplicate names and schema versions below 1 are rejected; callers are responsible for choosing a meaningful name.

The accepted definition shape is:

[
    'label' => 'Created', // optional
    'group' => 'account', // optional
    'weight' => 1, // optional
    'schema_version' => 1, // optional, positive integer
]

Defaults are derived from the event name:

  • group defaults to the part before the first .
  • label defaults to a headline version of the suffix after the first .
  • weight defaults to 1
  • schema_version defaults to the registry-owned version for the event, initially 1

The definition shape is declared by PHPDoc and static analysis. Runtime validation rejects duplicate names and schema_version values below 1; callers must supply the documented types. Empty label and group values are stored unchanged, and integer weights may be zero or negative. Callers remain responsible for supplying the documented types; for example, storing a non-integer weight can later violate the declared weight(): int return type.

Delivery contract versions

schema_version is stamped into delivery meta with event_id, occurred_at, resource_type, resource_id and resource_version. The OpenAPI 3.1 webhooks section publishes each registered event's HTTP schema and required signing headers. A breaking payload change increments that event's schema version; additive optional fields do not. Retried, redelivered and replayed events keep their captured version and event ID. See Webhooks for timestamped HMAC verification and recovery endpoints.

Identity, collisions, and grouping

Event identity is the event name itself.

  • register() throws InvalidArgumentException when the name is already present
  • registerMany() performs duplicate checks before mutating state, so collisions leave the registry unchanged

groups() sorts event groups alphabetically by group key. Each group exposes a human-readable label plus a flat list of event names.

names() preserves the registry's registration order. The webhook adapter and Livewire subscription picker use the current webhook-visible names, while REST request DTOs resolve the same list when their validation rules are evaluated. The wildcard (*) is an additional valid subscription value and expands at dispatch time to every currently visible core or plugin event.

Current core registrations and discovery guidance

The shipped catalogue is seeded from the configured EventDefinition catalogue and surfaced to users through the API console, webhook forms, and delivery jobs.

Representative shipped events include:

Event Group Current meaning
account.created account Account lifecycle creation
settings.updated settings Settings API update completed
document.pdf_generated document Document pipeline rendered a PDF
vehicle.assigned vehicle Fleet assignment event

Use the registry helpers instead of copying the full list:

  • names() supports runtime discovery and Livewire webhook-form validation
  • groups() powers grouped selection UI in resources/views/livewire/api/webhooks.blade.php
  • all() exposes the normalized metadata when you need labels, groups, and weights together

Relationship to the workflow catalogue

Both this registry and workflow authoring are seeded from the same EventDefinition catalogue, but they consume it differently, and the difference is easy to trip over.

  • system_protected events are absent from every discovery accessor, this registry included, so they can be neither subscribed to nor selected as a workflow trigger. They remain fully recorded — EventRegistry::get() / has() still return them for the recording path — they are simply not offered to any consumer. Flipping that flag is therefore not a workflow-local decision: it exposes the event to this webhook catalogue, the API console and the plugin SDK at the same time. Treat it as an API contract change.
  • Webhook subscribability does not imply workflow triggerability. A workflow trigger additionally needs a registered capability provider to resolve a subject, authorise it, redact the payload and pin a contract. Many events subscribable here are catalogue-only in the workflow editor. See docs/development/plugin-sdk-vs-workflows-vs-webhooks.md.
  • A webhook payload and a workflow trigger envelope are not the same shape, and deliberately so. Some emitters keep the broadcast payload deliberately lean where the full record is sensitive — CommunicationDraftEvents is the worked example: an unapproved draft body is withheld from subscribers, who re-read the record through the API with their own abilities.

Lookup and failure behavior

  • get($name) returns the normalized event definition or null
  • has($name) is the non-throwing existence check
  • weight($name) returns the stored weight, or 1 when the name is unknown

The registry itself does not dispatch events. It publishes the event catalogue that delivery and management flows consume.

Ordering and runtime consumption

The registry's weight value is about outbound metering, not delivery order.

App\Jobs\DeliverWebhook resolves get() and weight() on the first delivery attempt so it can:

  1. write price_weight and weighted_units to the webhook_logs row
  2. increment outbound daily usage on the webhook_sent channel using the event group as the metering resource

The management surfaces use the live EventRegistry boundary:

  • the Livewire webhook form validates against the runtime registry's names() output
  • REST CreateWebhookData and UpdateWebhookData validate subscriptions against EventRegistry::names('webhook') plus *

WebhookService::dispatch() is the single outbound authorization boundary: it enforces EventRegistry::names('webhook') before querying subscriptions or enqueueing jobs. DispatchWebhookForAuditableEvent and the document bridge retain their ownership, payload, and replay responsibilities, then delegate authorization and delivery to that service. Unknown, system-protected, and consumer-denied events are therefore ignored even for wildcard subscriptions. Existing wildcard subscriptions automatically receive newly visible core events and runtime plugin events. WebhookService::EVENTS is a fixed 245-event snapshot; dispatch authorization uses the live registry.

This makes every current webhook-visible event available as an explicit named REST subscription as well as through the wildcard.

Worked example

Plugins can register a webhook-visible event directly with the shared registry:

$registry = new WebhookEventRegistry;

foreach (app(EventRegistry::class)->names('webhook') as $name) {
    $registry->register($name);
}

With that registration in place:

  • names() includes settings.updated and document.pdf_generated
  • names() also includes the 25 audit-platform core events marked webhook-visible, plus later runtime plugin registrations
  • groups()['document']['events'] exposes the document events for the picker UI
  • weight('settings.updated') returns the default metering weight used by outbound usage recording