Webhooks

Subscribe to real-time event notifications delivered to your server via HTTPS.

Overview#

Webhooks let you receive real-time notifications when events happen in Signals. Register an endpoint URL, choose which events to subscribe to, and Signals will send a signed HTTP POST to your server whenever those events occur.

Managing Webhooks#

Webhooks can be managed via the API (/api/v1/webhooks) or from the admin panel at Admin > Settings > Webhooks.

Events#

The event catalogue is owned by the shared EventRegistry. Existing wildcard (*) subscriptions expand automatically when a new webhook-visible core or plugin event is registered.

Additional Registry Events#

Accounts#

Catalogue items#

Stock#

Flightcases#

Activities#

Addresses#

Conversations#

Rate specifications#

Tax#

Pricing#

Warehouses#

Currencies#

Exchange Rates#

Users#

Roles#

Settings#

Rentals#

Rental events fire on every committed mutation of a rental, its line items, costs, allocated assets, and quote versions. They are never re-delivered when the event warehouse is rebuilt.

Communication Drafts#

Payloads are lean envelopes — id, status, and the title pointer. A draft's body is customer prose that has not (yet) cleared the approval gate, so it is never broadcast; re-read /api/v1/communication_drafts/{id} for the content.

Documents#

Communication Templates#

Email Layouts & Templates#

Attachments#

Invoices#

Billing Runs#

Availability#

Shortages#

Purchase Orders#

Virtual Stock#

Vehicles#

Facilities#

Services#

Resource assignments#

Assignment route stops#

Scheduling conflicts#

Repair#

Equipment tests#

Asset Lifecycle#

Stock Checks#

Warehouse Transfers#

Rental Projects#

Supplier Costs#

Dispatch & Returns#

Scannable Identifiers#

Scan Sessions#

Reporting#

Import / Export#

Updates#

Event stability & deprecation#

Event names are a public contract. A subscription stores the names it wants verbatim, so a renamed or removed name simply stops matching and deliveries end silently — there is no error for the integration to see.

The policy is therefore:

• Additive only. New events may be added at any time. A released event name is never renamed and never removed.
• Payload changes are additive. Fields may be added to an event payload; existing fields are not renamed, retyped, or dropped. Subscribers should ignore unknown fields.
• Deprecation, not deletion. An event that is no longer recommended is documented as deprecated (and, in future, flagged as such in the catalogue with a sunset window). It keeps firing until the sunset passes.

This is enforced in CI, not just by convention: ReleasedEventNames::NAMES (tests/Support/Events/ReleasedEventNames.php) is a frozen snapshot of every released event name, and the ratchet in tests/Feature/Architecture/EventCatalogueRatchetTest.php fails if any of them disappears from config/events.php. Adding an event is free — append the new name to the snapshot.

Payload Format#

Every webhook delivery sends a JSON POST request with the event name and associated data:

{
    "event": "user.created",
    "timestamp": "2026-01-15T14:30:00Z",
    "data": {
        "user": {
            "id": 42,
            "name": "Jane Smith",
            "email": "[email protected]"
        }
    }
}

Actor attribution#

Every data object carries a reserved actor_type key naming who caused the event:

It is stamped once at the dispatch boundary, so it is present regardless of which part of the application produced the event.

actor_type answers who acted, which is not the same as how the call arrived. A request replayed through the in-process kernel is classified by its caller, not by the token it carries: MCP is an agent, the API Explorer is the user driving it, and the CLI is the system — so a token-authenticated artisan run is never reported as api.

Cross-entity reference (ref)#

Alongside actor_type, the data object carries an optional ref key naming the title of the event as a single addressable string:

"ref": "rental:123"

The format is entity:id — the entity slug is the first segment of the event name, and the id is the title's integer primary key. Primary keys elsewhere in the payload are unchanged; ref is an additive convenience for consumers correlating events across entities.

It is stamped at the dispatch boundary and is present when the title's id is unambiguous:

• the payload nests the entity's own object (data.rental.id for any rental.* event), or
• the event name is a two-segment entity.action and the payload carries a top-level id (the lean_envelope shape).

ref is absent when the title cannot be identified without guessing — for example sub-entity events such as account.address.created, whose top-level id belongs to the address rather than the account, and ad_hoc payloads that carry no id for the event's entity. Treat ref as optional and fall back to the ids in the payload body.

A producer that sets ref explicitly keeps its own value.

Payload Schemas#

Most events embed the affected resource under a singular key inside data, using the same shape the REST API returns. Lifecycle events that only need to identify a record (deletions, archive/restore) send just an id.

Each event declares its payload shape in the event catalogue:

Tax Rate Events#

tax_rate.created and tax_rate.updated include the full tax rate object:

{
    "event": "tax_rate.created",
    "timestamp": "2026-01-15T14:30:00Z",
    "data": {
        "tax_rate": {
            "id": 1,
            "name": "UK Standard",
            "description": "Standard rate VAT",
            "rate": "20.0000",
            "is_active": true,
            "created_at": "2026-01-15T14:30:00Z",
            "updated_at": "2026-01-15T14:30:00Z"
        }
    }
}

tax_rate.deleted sends only the identifier:

{
    "event": "tax_rate.deleted",
    "timestamp": "2026-01-15T14:30:00Z",
    "data": { "id": 1 }
}

Tax Rule Events#

tax_rule.created and tax_rule.updated include the full tax rule object:

{
    "event": "tax_rule.created",
    "timestamp": "2026-01-15T14:30:00Z",
    "data": {
        "tax_rule": {
            "id": 5,
            "company_tax_type_id": 1,
            "catalogue_item_tax_type_id": 2,
            "tax_rate_id": 1,
            "priority": 10,
            "is_active": true,
            "created_at": "2026-01-15T14:30:00Z",
            "updated_at": "2026-01-15T14:30:00Z"
        }
    }
}

tax_rule.deleted sends only the identifier:

{
    "event": "tax_rule.deleted",
    "timestamp": "2026-01-15T14:30:00Z",
    "data": { "id": 5 }
}

CatalogueItem Archive & Restore Events#

catalogue_item.archived and catalogue_item.restored are lifecycle transitions on an existing catalogue item and carry only its identifier. Fetch the current state from GET /api/v1/catalogue_items/{id} if you need the full record.

{
    "event": "catalogue_item.archived",
    "timestamp": "2026-01-15T14:30:00Z",
    "data": { "id": 42 }
}

Verifying Signatures#

Every delivery includes an X-Signals-Signature header containing an HMAC-SHA256 signature of the request body. Verify it against the secret you received when creating the webhook:

$signature = hash_hmac('sha256', $requestBody, $webhookSecret);

if (! hash_equals($signature, $request->header('X-Signals-Signature'))) {
    abort(401, 'Invalid signature');
}

Retry Behaviour#

Failed deliveries (non-2xx response or connection timeout) are retried with exponential backoff up to 6 times over approximately 12 hours. After 3 consecutive days of failures, the webhook is automatically disabled.

Re-enable a disabled webhook from the admin panel or by updating it via the API with is_active: true.

Delivery Logs#

Every delivery attempt is logged. View logs via the API at GET /api/v1/webhooks/{id}/logs or from the API Console Webhooks page by clicking the logs icon on a webhook row. Deliveries also appear in the unified Request Log on the webhook_sent channel.

Outbound metering weights#

Each outbound event carries a price weight (0–4) declared in WebhookEventRegistry. Weights default to 1 unless overridden at registration time. On the first delivery attempt of each job run, DeliverWebhook records the weight on the webhook_logs row and increments the webhook_sent daily rollup by the event's weight.

Weight 0 events are still logged but contribute zero weighted units toward usage totals.

Inbound webhook receiver#

Signals can accept webhook POSTs from external systems via registered inbound sources. Manage sources from the API Console at /api/webhooks (Inbound tab) or programmatically when that surface is exposed.

Receive URL#

POST {your-app-url}/webhooks/receive/{slug}

Replace {slug} with the source's URL slug. The route is public (no Sanctum token) — authentication is HMAC signature verification only.

Signature verification#

Each source stores a secret, signature algorithm (default sha256), and header name (default X-Signature). The middleware computes:

$expected = hash_hmac($source->signature_algo, $requestBody, $source->secret);
$provided = $request->header($source->signature_header);

$valid = is_string($provided) && hash_equals($expected, $provided);

Send the HMAC digest as a plain string in the configured header (not prefixed with sha256=).

Responses#

Inbound metering weights#

Unlike outbound events (code-defined in WebhookEventRegistry), inbound weights are stored per source in inbound_webhook_sources.price_weight (0–4, editable in the console). Valid requests meter on the webhook_received channel; invalid signatures log detail rows but do not increment weighted units.

Inbound logs#

Receipts are stored in inbound_webhook_logs and surfaced in the Request Log (webhook_received channel) and the source's logs modal in the API Console.