Webhooks

Receive device events and verify signed payloads in your receiver.

Device events

Active webhook subscriptions are associated with fleets and events. Matching device events dispatch delivery jobs through the webhook queue.

A payload includes device_id and event, merged with the event’s own parameters:

{
  "device_id": 1001,
  "event": "<event-name>"
}

Replace <event-name> with an event available to your subscription. Confirm the event names and parameters before implementing your receiver. Webhook registration is not covered by this API reference.

Verify the signature

Outbound delivery includes an X-Signature header. The PHP SDK provides SHA-256 time-limited signature verification:

use Katsana\Sdk\Signature;

$verifier = new Signature($yourWebhookSecret);
$isValid = $verifier->verify($signatureHeader, $rawRequestBody, 3600);

Use the exact raw request body. Re-encoding parsed JSON can change the bytes being verified. The verifier’s threshold defaults to 3600 seconds; choose a threshold appropriate for your receiver’s delivery requirements.

The Laravel wrapper includes a webhook FormRequest helper. Its header lookup uses an underscore spelling while outbound delivery uses X-Signature. Check your framework and proxy’s header normalization before using the helper unchanged.

Handle deliveries

Retry timing, delivery ordering, duplicate behavior, response timeouts and event-specific payloads are not specified here. Do not assume exactly-once delivery. Keep secrets in your receiver’s private configuration and avoid logging signed bodies that contain customer data.

The OpenAPI downloads describe the request/response API; they do not include webhook definitions.