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#

Members#

Products#

Stock#

Containers#

Activities#

Rate Definitions#

Tax#

Users#

Roles#

Settings#

Opportunities#

Opportunity events fire on every committed mutation of an opportunity, its line items, costs, allocated assets, and quote versions. They are never re-delivered when the event store is rebuilt.

Documents#

Invoices#

Availability#

Shortages#

Purchase Orders#

Virtual Stock#

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": "jane@example.com"
        }
    }
}

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.

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,
            "organisation_tax_class_id": 1,
            "product_tax_class_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 }
}

Product Archive & Restore Events#

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

{
    "event": "product.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.