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 asdata.idfor a registered single-DTOrental.*event), or - the event name is a two-segment
entity.actionand the internal payload carries anid, delivered asdata.id(thelean_envelopeshape).
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.