SIGNALS Docs
Exit Reader View
100%
Theme

Plugin inbound requests

Declared plugin routes and signed core receivers for inbound integrations.

Plugin routes (SDK v2)

Declare every route in signals.yaml, then register its method and path with PluginRegistrar::routes(). These examples belong to a package with sdk: "^2.0" (or "^2.1"):

routes:
  - path: status
    method: GET
    auth: public
    rate_limit: 10
  - path: sync
    method: POST
    auth: api
    ability: plugins:write
    rate_limit: 60
  - path: callback
    method: POST
    auth: verifier:callback
    rate_limit: 600

Routes mount at /api/v1/plugins/{vendor}/{name}/{path} and exist only while the package is enabled. public needs no identity and shows an administrator warning. api requires an active API user and the declared token ability; handlers must still authorize their specific operation. verifier:name calls a named verifier before dispatch. Validate incoming payloads in the handler and make side effects idempotent.

use App\Sdk\Http\HeaderSecretVerifier;
use App\Sdk\PluginContext;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

$registrar->verifier('callback', new HeaderSecretVerifier(
    fn (): string => $context->setting('callback_secret', ''),
));
$registrar->routes('POST', 'callback', function (PluginContext $context, Request $request): JsonResponse {
    $values = $request->validate(['receipt_id' => ['required', 'string', 'max:120']]);
    $context->log('Callback accepted', ['receipt_id' => $values['receipt_id']]);

    return response()->json(['accepted' => true]);
});

Declare callback_secret as an encrypted secret setting. Register a handler for each declared route, including GET status and POST sync if using the full manifest above. Generic HmacBodyVerifier and HmacUrlVerifier support signed bodies and signed URLs; plugins do not need to implement cryptography.

Public routes are limited to ten requests per IP/minute and API routes to sixty per IP/minute. Those limits are fixed even if another rate_limit is declared. Verified routes default to 600 per minute per provider and route; rate_limit can be 1–6000. Invalid signatures do not consume that verified budget. ?provider_id=123 selects an active channel provider belonging to the package and gives its exact-host network grant inside the callback. Without it, the budget is package/route scoped and there is no operator-host grant. Audits contain package/path/auth, never request secrets. See Inbound routes and tracking.

Core receivers

Core receivers remain alternatives for their supported purposes; a catalogue listener alone does not create an HTTP endpoint.

Endpoint Purpose
POST /api/v1/workflows/{workflow}/inbound/{credentialKey} Queue an active published inbound workflow; route name api.v1.workflow-inbound-runs.store
POST /api/v1/notifications/inbound/{provider} Accept delivery-tracking updates for a registered provider; route name api.v1.notifications.inbound

Both use signature verification instead of a user session or Sanctum token. SignedInboundRequest signs timestamp + "." + rawBody with HMAC-SHA256, checks timestamp skew and compares signatures with hash_equals. Default headers are X-Signature and X-Timestamp, with a 300-second tolerance. Send exactly the bytes used for signing.

Workflow example

Configure an integration credential allowed to start the intended active, published inbound workflow. The workflow receiver currently accepts a rental subject and a trigger input object. For example, an external review system can send:

{
  "subject": {"type": "rental", "id": 42},
  "input": {"review_reference": "REV-42"}
}

On the sender, calculate the signature over the raw JSON body:

$timestamp = (string) time();
$body = json_encode([
    'subject' => ['type' => 'rental', 'id' => 42],
    'input' => ['review_reference' => 'REV-42'],
], JSON_THROW_ON_ERROR);
$signature = hash_hmac('sha256', $timestamp.'.'.$body, $integrationSecret);

Send $body to the workflow receiver with those timestamp/signature headers and Content-Type: application/json. The workflow verifier matches the credentialKey UUID regardless of letter case, then checks the credential, allowed workflow, timestamp, replay protection and admission limits before accepting work. Failed signatures are limited to 60 a minute per credential and sending address; valid deliveries do not count against that limit. An oversized body returns 413 and an unsupported content type returns 415 before work is accepted. A successful request returns 202 with the accepted run reference; it does not mean the workflow has finished.

Have the workflow perform a supported core action that publishes a plugin-visible event, then subscribe to that event through listen(). For instance, if the workflow performs an action that emits rental.updated, the plugin can receive the published event:

use App\Sdk\Hooks\PluginEventPayload;
use App\Sdk\PluginContext;

$registrar->listen('rental.updated', function (PluginContext $context, PluginEventPayload $payload): void {
    $context->log('Rental workflow activity observed', ['ref' => $payload->ref()]);
});

The listener sees the core event's published payload, not automatically the incoming JSON or a workflow completion callback. It may also receive the same event from other callers. Choose events using the catalogue and design correlation explicitly.

Notification delivery tracking

Register a provider through deliveryTrackingResolver(). The receiver requires that provider to exist, reads notifications.inbound_{provider}_secret and configurable signature/timestamp header settings, then asks its resolver to produce DeliveryTrackingUpdateData. Unknown providers return 404; failed signatures return 403; unrecognised payloads return 422. Accepted updates are queued on notifications and acknowledged with 202.

This receiver handles notification delivery status; it is not a general plugin webhook router. Provider delivery transport and delivery-tracking resolver registration are separate responsibilities.