4.2.2 Integrations — Webhooks & Automation — Incoming Hooks — Validation and Security

Incoming Webhooks allow external systems to send events or commands into Praisma Hub in a controlled and secure manner. They provide a standardized ingestion mechanism for automation and system-to-system communication while enforcing strict validation and isolation rules.

Endpoint Definition

Incoming webhook endpoints are explicitly defined and tenant-scoped. Each endpoint is associated with a specific purpose and processing pipeline.

Endpoint properties:

Unique endpoint identifier

Accepted HTTP methods

Expected payload schema

Security configuration

Endpoints are never generic or open-ended.

Authentication and Verification

All incoming webhook requests must be authenticated. Authentication mechanisms depend on endpoint configuration.

Supported methods:

Shared secret signatures

Token-based headers

IP allowlists where applicable

Example signature verification:

$signature = hash_hmac('sha256', $rawPayload, $secret); if (!hash_equals($signature, $request->header('X-Signature'))) { abort(401); }

Payload Validation

Incoming payloads are validated against predefined schemas before processing. Invalid or malformed payloads are rejected deterministically.

Validation rules include:

Required fields and types

Size limits

Version compatibility

Example validation:

$request->validate([ 'event' => 'required|string', 'data' => 'required|array' ]);

Processing Model

Validated webhook events are processed asynchronously. Execution is decoupled from request handling to protect system availability.

Processing characteristics:

Queued execution

Idempotent handlers

Explicit failure handling

Idempotency and Replay Protection

Incoming hooks support idempotency to prevent duplicate processing during retries or replays.

Example idempotency guard:

if (WebhookEvent::alreadyHandled($eventId)) { return response()->noContent(); }

Error Handling and Responses

Webhook endpoints return deterministic HTTP responses. Errors do not leak internal details.

Response behavior:

2xx for accepted events

4xx for validation or authentication failures

5xx only for transient internal errors

Rate Limiting and Abuse Protection

Endpoints are protected against abuse through rate limiting and payload size enforcement.

Protection measures:

Request throttling

Payload size caps

Automatic suspension on repeated violations

Security and Isolation

Incoming webhook processing is tenant-scoped. Handlers execute with minimal privileges and cannot access unrelated data. All requests and outcomes are logged for audit and diagnostics.