SIGNALS Docs
Reader View

Webhooks

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

Rental state transitions emit rental.state_changed with the usual id and action envelope plus from and to. Document changes use enquiry, quote, and order. Returns to an active status use status identifiers such as quote_lost → quote_pencilled or order_complete → order_active; configured statuses use their underlying system status for this transition evidence. Status updates and fulfilment promotions retain rental.status_changed and rental.status_promoted. Asset status corrections emit rental.asset_status_changed with assignment_id, from, and to (for example on_hire → allocated).

Guard keys follow rental.transition.<target>, including order, quote, enquiry, and active. The workflow handler rentals.transition.order confirms an order with the same approval, credit and shortage checks; its optional to input accepts only order. Its target-specific identifier preserves the handler's order-specific retry and approval contract. Workflow filters for order confirmation must require trigger.payload.from = quote and trigger.payload.to = order.

Rental payloads use the same flat fields as REST and MCP, including starts_at, uses_billable_days, customer_collects, subtotal, tax_total and total. Choice fields are booleans, and monetary values are decimal strings with currency metadata. See Rental fields.

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 API console at /api/webhooks (the original /admin/settings/webhooks URL redirects there).

Events

The event catalogue — every event name, its trigger, the event stability policy, and the payload schemas for events that send more than the resource — is on Webhook event catalogue.

Payload Format

Every webhook delivery sends a JSON POST request with the event result in data and delivery attributes in meta, including event and timestamp:

{
    "data": {
        "id": 42,
        "name": "Jane Smith",
        "email": "[email protected]"
    },
    "meta": {
        "event": "user.created",
        "timestamp": "2026-01-15T14:30:05+00:00",
        "event_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "occurred_at": "2026-01-15T14:30:00.123456Z",
        "resource_type": "user",
        "resource_id": 42,
        "resource_version": "2026-01-15T14:30:00.000000Z",
        "schema_version": 1
    }
}

timestamp is when this attempt was sent. These meta fields are present on every event:

Field Type Description
event_id string Stable UUID for the event. The same value is sent on every retry, redelivery and replay — use it to de-duplicate. Also sent as the X-Signals-Event-Id header.
occurred_at string When the domain event happened (ISO 8601 UTC), not when this attempt was sent.
resource_type string The subject entity — the first segment of the event name (rental for rental.updated).
resource_id integer|string|null The subject's id, taken from ref; null when the subject cannot be identified unambiguously.
schema_version integer Payload contract version owned by the event registry. Starts at 1 for each event; a breaking payload change increments only that event's version. Retries, redeliveries and replays keep the version stamped when the event was dispatched.
resource_version string|null The subject's updated_at when the payload carries it, otherwise null.

The OpenAPI 3.1 export includes a top-level webhooks entry for every registered event, with its delivery schema and required signing headers. Additive optional fields do not require a schema version bump.

Ordering

Deliveries are not guaranteed to arrive in the order events occurred: each delivery is queued and retried independently, so a retried older event can land after a newer one. To apply changes in order, compare meta.resource_version (or meta.occurred_at when the version is null) against what you have stored for resource_type + resource_id, and ignore anything older. De-duplicate on meta.event_id.

Actor attribution

Delivery meta carries a reserved actor_type key naming who caused the event:

Value Meaning
user A signed-in person acting in the web UI, including via the built-in API Explorer
api An external caller using an API token
agent An AI agent acting over MCP
system Scheduled work, queue jobs, artisan commands, or an internal process

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, meta 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 event carries the entity's own object (promoted to data, such as data.id for a registered single-DTO rental.* event), or
  • the event name is a two-segment entity.action and the internal payload carries an id, delivered as data.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 data.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.

Event-specific payload shapes are listed in Webhook event catalogue → Payload Schemas.

Verifying Signatures

Every delivery carries these headers:

Header Value
X-Signals-Event-Id Same stable event identifier as meta.event_id; use the verified body to de-duplicate
X-Signals-Timestamp Unix time (seconds) the attempt was signed
X-Signals-Signature Hex HMAC-SHA256 of {X-Signals-Timestamp}.{raw request body}, keyed with the secret you received when creating the webhook

Verify the signature over the exact raw body, then reject any request whose timestamp is more than 5 minutes (300 seconds) from your clock — this replay window stops a captured request being re-sent later:

$timestamp = $request->header('X-Signals-Timestamp');
$expected = hash_hmac('sha256', $timestamp.'.'.$requestBody, $webhookSecret);

if (! ctype_digit((string) $timestamp)
    || abs(time() - (int) $timestamp) > 300
    || ! hash_equals($expected, (string) $request->header('X-Signals-Signature'))) {
    abort(401, 'Invalid signature');
}

Each attempt (including retries, redeliveries and replays) is signed afresh with its own timestamp, so a legitimate retry always falls inside the window. Use meta.event_id to recognise a repeat of an event you already processed.

Migrating from body-only signatures. Earlier builds signed the raw body alone. The header name is unchanged; receivers must now prefix the body with {timestamp}. before computing the HMAC.

Retry Behaviour

Failed deliveries (5xx response or connection error/timeout) are retried with increasing delays of 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, for up to 6 attempts in total. A 4xx response is logged as a failure but not retried. Each failed attempt counts toward a consecutive-failure streak, and any successful delivery resets it. After 18 consecutive failed attempts the webhook is automatically disabled. Test deliveries do not count toward the streak.

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

Test, redeliver and replay

Endpoint Effect
POST /api/v1/webhooks/{id}/test Queues a signed signals.test ping (or, with {"event": "<name>"}, a sample payload for a registered event). Reaches auto-disabled endpoints; never counts toward the failure streak.
POST /api/v1/webhooks/{id}/deliveries/{delivery}/redeliver Re-sends one logged delivery ({delivery} is a log id from GET /webhooks/{id}/logs) with its original meta.event_id and meta.occurred_at.
POST /api/v1/webhooks/{id}/replay Body {"from": "<ISO 8601>", "to": "<ISO 8601>"}. Re-sends each distinct event logged in the range (by log time, inclusive) once, oldest first. Test pings are skipped; at most 1000 events per call, with truncated: true when more matched.

All three return 202 Accepted, require webhooks.manage with the webhooks:manage token ability, and are limited to webhooks you own (owners may act on any). Redelivered and replayed payloads are the logged ones; for account events those are already minimised.

Recovery examples

Queue the default test ping:

POST /api/v1/webhooks/7/test
Content-Type: application/json

{}
{"data":{"event":"signals.test","queued":true}}

Redeliver a retained log entry belonging to that webhook:

POST /api/v1/webhooks/7/deliveries/91/redeliver
{"data":{"delivery_id":91,"event":"rental.updated","event_id":"9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d","queued":true}}

Replay an inclusive log-time range:

POST /api/v1/webhooks/7/replay
Content-Type: application/json

{"from":"2026-11-04T00:00:00Z","to":"2026-11-04T12:00:00Z"}
{"data":{"from":"2026-11-04T00:00:00+00:00","to":"2026-11-04T12:00:00+00:00","queued":12,"truncated":false}}

These are 202 queue acknowledgements, not proof of delivery. If data.truncated is true, narrow the time range and deduplicate overlapping events. Recovery is limited to retained logs; use incremental resource reads to reconcile gaps beyond retention.

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 sending applications 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 records a secret, signature algorithm (default sha256), and header name (default X-Signature). The middleware computes:

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

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

Send the Unix timestamp in X-Signals-Timestamp and the HMAC digest as a plain string in the configured signature header (not prefixed with sha256=). The signed message is the timestamp, a period, and the exact raw request body. Timestamps must be within 300 seconds of the server clock, including future skew. Only failed signatures count toward the limit of 60 per minute per source slug, IP and tenant/host; successful deliveries do not consume that limit; rejected requests do not create inbound delivery rows or consume weighted units.

Each source selects signature_scheme: timestamped (the default described above) or body. Body mode verifies the HMAC over only the raw body, using the configured header and SHA-256/SHA-512 algorithm; no timestamp header is required. Body mode has no replay window and should be selected only for senders that cannot sign a timestamp. The consumer must deduplicate provider event identifiers. Configure the scheme in the inbound source create/edit form.

Responses

Status Condition Body
200 Valid signature {"status":"received"} — fires InboundWebhookReceived
401 Missing, invalid, or expired signature/timestamp {"message":"Invalid signature"} — no delivery row
429 Request limit exceeded Retry after the response’s Retry-After interval
404 Unknown slug or inactive source Laravel 404 page

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 are rejected before detail logging and 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.